Perforce TeamHub configuration

The P4 DAM configuration settings are in the /var/opt/hth/shared/hth.json configuration file. It includes settings manipulated through the TeamHub admin UI. This configuration file is also part of P4 DAM Backups, if enabled.

Every time P4 DAM is reconfigured, the configuration file is read and the configuration is applied to all of P4 DAM services. Some of the configuration flags dictate what mode of deployment P4 DAM is running, where others simply override default P4 DAM settings.

Format

The configuration file is formatted as JSON. It is important to keep the correct format of the file, otherwise the P4 DAM reconfiguration will not work. JSONLint is a trusted open-source JSON linter option to help verify the syntax of the JSON contents.

Duplicated keys override any previously defined keys.

To see the current configuration applied to the server, run the following command:

sudo hth-ctl show-config

Overriding defaults

P4 DAM comes with many sensible defaults for both service and application behavior. If the default configuration needs to be adjusted, use the dictionary provided below as a reference.

Each configuration flag has a section, for example app, nginx, etc. These sections separate settings into logical categories. To use the dictionary, simply merge the section to the existing configuration file at /var/opt/hth/shared/hth.json with a required key and value.

Whenever changing any of the configurations, pay attention to the type of the key and where available refer to the linked documentation. Also, remember that configuration is not applied until the sudo hth-ctl reconfigure command has been run.

Section: apache

This section groups P4 DAM Apache-related settings.

Key Type Default Description
limit_request_body Integer null Specifies the number of bytes that are allowed in a request body. See LimitRequestBody Directive.
limit_xml_request_body Integer null Limit (in bytes) on maximum size of an XML-based request body. See LimitXMLRequestBody Directive.
timeout Integer 120 Defines the length of time Apache httpd will wait for I/O

Section: app

This section groups instance and general application-related settings.

Key Type Default Description
backups_email String email Allows overriding receiver of backup related emails.
default_company String Default company short name to use with login
email String support@FQDN Email of the sender of all outgoing emails and links to Support team
hostname String FQDN TeamHub application hostname
http_proxy String Defines HTTP proxy to use with external services like hooks. Provide absolute url including possible credentials: http://user:password@proxy.com:8008.
is_cluster Boolean false Defines whether P4 DAM runs in Enterprise mode
is_https Boolean false Defines whether P4 DAM generates URLs with https or http.
is_ssl Boolean false Defines whether P4 DAM services are running with SSL/TLS using certificates on the server instance (true) or offloaded to a load balancer (false).
notifications_email String email Allows overriding sender of notification related emails.
registrations_email String email Allows overriding sender of registration related emails.
ssh_port Integer 22 Defines SSH port for Git and Mercurial clone urls when the instance is using non-standard SSH port.

Section: audit

This section groups P4 DAM audit logging-related settings.

Key Type Default Description
logrotate_frequency String daily Frequency of logrotate rotation
logrotate_rotate Integer 90 Number of logrotate files to keep
logrotate_size Integer Size of logrotate rotation. Does not rotate by size by default.

Section: backend

This section groups TeamHub backend (APIs, TeamHub admin UI) application-related settings.

Key Type Default Description
auth_method String helix

Defines P4 DAM Authentication type. Allowed: helix.
backup_s3 Boolean false Defines whether asset backups need to be taken offline to Amazon S3. Requires backups section configuration.
backups Boolean false Defines whether P4 DAM asset backups are enabled
command_timeout Integer 60 Timeout for command execution, in seconds
company_disk_usage_calculator_queue_size Integer 1 Number of workers performing company disk usage calculation jobs
db_host String localhost MongoDB hostname for Enterprise setup
db_password String MongoDB password
db_pool_size Integer 10 MongoDB connection pool size
db_port Integer 4002 MongoDB port
db_username String MongoDB username
diff_file_max_bytes Integer 51200 Maximum number of bytes for a file in a diff
diff_max_bytes Integer 1024000 Maximum number of bytes for a diff output
diff_max_files Integer 150 Maximum number of files in a diff
diff_max_lines Integer 50000 Maximum number of lines in a diff
diff_process_max_bytes Integer 2048000 Maximum number of bytes to process for a diff
diff_timeout Integer 5 Timeout for generating a diff, in seconds
es_hosts Array [] Array of Elasticsearch host hashes. Supported keys are: host, port, scheme, user, password.
es_index_prefix String null Defines the optional index name prefix for Elasticsearch indexesndices
es_number_of_replicas Integer 1 Defines the number of replicas for Elasticsearch indexes
es_number_of_shards Integer 5 Defines the number of shards to use with Elasticsearch indexes
es_ssl_verify Boolean true Defines whether to validate Elasticsearch host certificate
es_timeout Integer 55 Elasticsearch request timeout, in seconds
events_queue_size Integer 2 Number of workers performing event jobs
failed_login_interval Integer 2 Minimum time between failed login attempts
failed_login_limit Integer 6 Limit of failed login attempts in specified time frame
failed_login_period Integer 60 Time frame for failed_login_limit
hooks_queue_size Integer 2 Number of workers performing repository event jobs
index_queue_size Integer 1 Number of workers performing code search indexing jobs
license_expire_notify String 30,14,7,3 Defines the intervals (number of days) before license expiration to notify instance administrators through email
merge_queue_size Integer 2 Number of workers performing merge jobs
merge_timeout Integer 120 Timeout for code review merge, in seconds
multipart_file_limit Integer 128 P4 DAM only: The maximum number of parts with a filename a request can contain. Accepting too many parts can lead to the server running out of file handles. Affects how many files can be uploaded at once. See multipart_file_limit.
multipart_total_part_limit Integer 4096 P4 DAM only: The maximum total number of parts a request can contain of any type, including both file and non-file form fields. Affects how many files can be uploaded at once. See multipart_total_part_limit.
tag_files_limit Integer 10000 P4 DAM only: The maximum total number of files that can be tagged and untagged at once. Setting this value too high can lead to the server out of file handles.
password_expire_count Integer 0 Defines the number of old passwords that cannot be used again. Value of 0 allows reusing old passwords.
password_expire_days Integer 0 Defines the maximum number of days a password can be used before it expires. Value of 0 means that passwords never expire.
password_expire_notify Integer 7 Defines the number of days before password expiration to notify accounts
password_validation_entropy Integer -1

The password_validation_entropy configuration flag defines the minimum password entropy level required related to the email, short_name, first_name, last_name field values using the Levenshtein algorithm.

  • ≤ 0 (zero): turns password entropy validation off. The default value is -1, password entropy validation off.

  • 0 (zero): P4 DAM only rejects the password if it is an exact match to one or more of the fields above.

  • ≥ 0 (zero): defines the minimum threshold of similarity required for a password.

password_validation_format String /(?=.*[[:upper:]])(?=.*[[:lower:]])(?=.*[[:digit:]]).*/

Defines the password format requirements for account password validation. By default, password validation requires a minimum of one uppercase letter, one lowercase letter, and one digit.

To remove the requirement for a specific password validation format, set password_validation_format to /.*/
password_validation_range String 8..100 Defines the minimum and maximum length for account password validation
redis_host String localhost Redis hostname for Enterprise setup
redis_password String Redis password
redis_port Integer 6379 Redis port
repository_gc_queue_size Integer 1 Number of workers performing garbage collection jobs

search_engine

String

null

Defines the search engine used by P4 DAM. See Step 4: Connect P4 DAM to P4 Search.

Supported value:

  • Search enabled using P4 Search: p4search

Section: backups

This section groups Backups and restoration-related settings.

Key Type Default Description
keep Integer 30 How many backups to keep before oldest backup gets removed (Archival method only)
s3_access_key String Amazon S3 access key for offline backups
s3_bucket String Amazon S3 bucket name for offline backups
s3_key_id String Amazon S3 key ID for offline backups
s3_region String Amazon S3 region for offline backups

Section: docker_registry

This section groups TeamHubDocker Registry-related settings.

Key Type Default Description
backups Boolean false Whether Docker backups are enabled
backups_keep Integer 5 How many backups to keep before oldest backup gets removed
log_level String warn Log level for Docker service
storage_driver String filesystem Docker storage driver to use. See Docker Registry
storage_settings Object   Docker storage driver options. See Docker Registry storage driver on the Docker website.

Section: gconn

This section groups the Git Connector (Gconn) settings.

Key Type Default Description
helix_user String null P4 Server user of Git Connector
host String null Hostname of the server Git Connector is installed on
https_enabled Boolean false Defines whether https is enabled or disabled for Git Connector
https_port Integer null Https protocol port.
ssh_enabled Boolean false Defines whether SSH  is enabled or disabled for Git Connector
ssh_port Integer null SSH protocol port
user String null OS user of the Git Connector

Section: helix

This section groups P4 Server connection settings.

Key Type Default Description
charset String utf8 Character set encoding on the P4 Server. For example, utf8or none.

groups_exclude_regex

String

  

Names of groups to exclude from mirroring between P4 Server and TeamHub, specified as a comma-delimited list of Ruby regular expressions. Example:

^swarm-group$

The specified groups do not appear in the TeamHub UI.

By default, TeamHub ignores all groups starting with HTH- and all legacy Perforce product groups in P4 Server, such as P4 Code Review groups.

groups_include_regex

String

  

Names of groups to include when mirroring between P4 Server and TeamHub, specified as a comma-delimited list of Ruby regular expressions. Example:

^swarm-group$

The specified groups appear in the TeamHub UI.
p4port String null Hostname or IP address and port for the P4 Server, in the form of: host:port
password String null Password or ticket for the P4 Server super user
sync_interval String */5 * * * * Interval to sync with the P4 Server. Set in Cron format. Default is every 5 minutes.
timeout Integer 55 P4 Server request timeout, in seconds
user String null An existing P4 Server user with super level privileges. This user must have unlimited ticket timeout.

users_exclude_regex

String

 

Names of users exclude from mirroring between P4 Server and TeamHub, specified as a comma-delimited list of Ruby regular expressions. Example:

^(user1|user2)$

The specified users do not appear in the TeamHub UI.

users_from_groups_exclude_regex

String

  

Names of groups to exclude users from when mirroring between P4 Server and TeamHub, specified as a comma-delimited list of Ruby regular expressions. Example:

^perforce-group$

The users from the specified groups do not appear in the TeamHub UI.

users_from_groups_include_regex

String

 

Names of groups to include users from when mirroring between P4 Server and TeamHub, specified as a comma-delimited list of Ruby regular expressions. Example:

^perforce-group$

The users from the specified groups appear in the TeamHub UI.

users_include_regex

String

  

Names of users to include when mirroring between P4 Server and TeamHub, specified as a comma-delimited list of Ruby regular expressions.Example:

^(user1|user2)$

The specified users appear in the TeamHub UI.

Section: logging

This section groups TeamHub logging-related settings.

Key Type Default Description
logrotate_frequency String daily Frequency of logrotate rotation
logrotate_rotate Integer 30 Number of logrotate files to keep
logrotate_size Integer Size of logrotate rotation. Does not rotate by size by default.
svlogd_num Integer 30 Number of SV log files to keep
svlogd_size Integer 209715200 The maximum size when SV rotation should happen (200MB)
svlogd_timeout Integer 86400 Number of seconds when SV rotation should happen (24 hours)

Section: mongodb

This section groups TeamHub MongoDB database related settings, which are usually required in or HA deployment for tools such as TeamHub Backups accessing MongoDB database.

Key Type Default Description
backup_s3 Boolean false Defines whether MongoDB backups need to be taken offline to Amazon S3. Requires backups section configuration.
backups Boolean false Defines whether TeamHub MongoDB backups are enabled
password String MongoDB password
port Integer 4002 MongoDB port
username String MongoDB username

Section: nginx

This section groups TeamHub Nginx-related settings.

Key Type Default Description

admin_allowed_ips

Array

[]

Limit access to the administrator UI to specified IP addresses or CIDR (Classless Inter-Domain Routing).

allowed_hosts

Array

[]

Specify the hosts that can connect to TeamHub, this mitigates host header injection attacks.

  • [] All hosts can connect to TeamHub. This is the default value.

  • ["https://other1.com", "https://other2.com"] An array of specific hosts that can connect to TeamHub.

cors_allowed_domains

String or an array of strings

"*"

Cross-Origin Resource Sharing (CORS) controls the external domains that can be used with TeamHub.

  • "*" An asterisk allows any domain. This is the default.
  • "" An empty string disables CORS support.
  • ["https://other1.com", "https://other2.com"] An array of specific external domains to support for CORS.
For more information about CORS, see Cross-Origin Resource Sharing (CORS).

csp_header

String

default-src 'self'; style-src 'self' 'unsafe-inline'; img-src * data: blob:

Content-Security-Policy header. An empty value omits the header.

To use the Content-Security-Policy header with the Safari browser, an additional connect-src policy directive is needed. For example, for the example.com domain:

  • example.com instance configured to use SSL/TLS, append: ; connect-src 'self' wss://example.com;

  • example.com instance not configured to use SSL/TLS, append: ; connect-src 'self' ws://example.com;

enable_sslv3

Boolean

false

Whether SSLv3 should be enabled. See Poodle vulnerability.

keepalive_timeout

Integer

65

Number of seconds for keep-alive connection

max_body_size

String 4G Maximum size of client request body
proxy_read_timeout

Integer

120

Number of seconds for reading a response from backend services

proxy_send_timeout

Integer

120

Number of seconds for sending a request to backend services

request_limit_burst

Integer

50

Number of requests a client can make over the rate specified in request_limit_rate

request_limit_enable

Boolean

false

Enable or disable request limiting. To learn more about rate limiting, see Rate Limiting with NGINX.

request_limit_nodelay

Boolean

true

Indicates whether to space out forwarding of queued requests

request_limit_rate

Integer

20

Maximum number of requests to perform per second

request_limit_whitelist

Array

[]

List of IP addresses to exclude from rate limiting

server_names

String

_

Server names nginx will listen on

ssl_ciphers

String

See default nginx ciphers below [1]

Specifies enabled ciphers in the format understood by the OpenSSL library

ssl_protocols

String

TLSv1.2 TLSv1.3

SSL/TLS protocols to enable

worker_connections

Integer

1024

Number of Nginx simultaneous worker connections

worker_processes

Integer

2

Number of Nginx worker processes to start

[1] Default nginx ciphers:

ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305

Section: opensshp

This section groups OpenSSH-related settings.

Key Type Default Description
enable Boolean false Whether the bundled OpenSSH is used or not. See OpenSSH.

Section: p4search

P4 DAM only: This section groups related settings for the Elasticsearch instance used by P4 Search.

Key Type Default Description
es_hosts Array [] Array of Elasticsearch host hashes. Supported keys are: host, port, scheme, user, password.
es_index String null Defines the Elasticsearch index name used by P4 Search.
es_ssl_verify Boolean true Defines whether to validate the Elasticsearch host certificate.
es_timeout Integer 55 Elasticsearch request timeout, in seconds.
ssl_verify Boolean true Defines whether to validate the P4 Search host certificate.

Section: postfix

This section groups TeamHub local Postfix MTA mailing settings.

Key Type Default Description
masquerade_domain String Domain of the email key Masquerade domain
message_size_limit Integer 20000000 Max size of the message in bytes
password String Password for SASL authentication
relay_host String Relay hostname
relay_port Integer 25 Relay port
sasl_auth_enable Boolean false Whether SASL authentication is enabled
tls_auth_enable Boolean false Whether TLS is used
tls_ca_crt_bundle String TLS CA certificates file
user_name String Username for SASL authentication

Section: redis

This section groups Redis-related settings.

Key Type Default Description
password string   Redis server password
port Integer 6379 Redis server port

Section: repos

This section groups TeamHub repository-related settings.

Key Type Default Description
backups Boolean false Defines whether TeamHub repository backups are enabled

Section: unicorn_backend

This section groups TeamHub backend (APIs, TeamHub admin UI) Unicorn server-related settings.

Key Type Default Description
backlog_socket Integer 64 Unicorn socket backlog size
worker_processes Integer 4 Number of Unicorn worker processes to start
worker_timeout Integer 60 Number of seconds Unicorn worker times out