Helix TeamHub configuration

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

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

Format

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

Note

Remember that duplicate keys override the previously defined keys.

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

sudo hth-ctl show-config

Overriding defaults

TeamHub 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 TeamHub 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:[email protected]:8008.
is_cluster Boolean false Defines whether TeamHub runs in Cluster or HA mode
is_https Boolean false Defines whether TeamHub generates URLs with https or http.
is_ssl Boolean false Defines whether TeamHub services are running with SSL 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 TeamHub 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) application-related settings.

Key Type Default Description
auth_method String builtin Defines TeamHub Authentication type. Allowed: builtin, ldap, or both
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 TeamHub 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 Cluster or HA 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 in seconds for generating a diff
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 indices.
es_number_of_replicas Integer 1 Defines the number of replicas for Elasticsearch indices.
es_number_of_shards Integer 5 Defines the number of shards to use with Elasticsearch indices.
es_ssl_verify Boolean true Defines whether to validate Elasticsearch host certificate.
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
ldap_collaborators_base String LDAP search base for collaborators
ldap_collaborators_enabled Boolean false LDAP authentication for collaborators
ldap_collaborators_filter String LDAP search filter used when finding collaborators
ldap_domain_base String LDAP search base for users
ldap_email String LDAP account email field mapped to TeamHub email
ldap_encryption String plain LDAP encryption. Allowed: plain, start_tls, simple_tls
ldap_filter String LDAP search filter used when finding users
ldap_first_name String LDAP account first name field
ldap_groups String LDAP field defining users groups
ldap_groups_base String LDAP groups search base
ldap_groups_from_user Boolean false LDAP users contain group information
ldap_host String LDAP hostname
ldap_interface_max_connections Integer 10000 Maximum connections for a child process until it is replaced with a new fork in the LDAP interface
ldap_interface_max_idle Integer 10 Maximum idle time, in seconds, for a child process after stopping serving requests until it is replaced with a new fork in the LDAP interface
ldap_interface_max_servers Integer 32 Maximum number of forked child processes in the LDAP interface
ldap_interface_min_servers Integer 4 Minimum number of forked child processes in the LDAP interface
ldap_interface_timelimit Integer 30 Maximum server-side time limit, in seconds, for a request in the LDAP interface
ldap_last_name String LDAP account last name field
ldap_password String LDAP search password
ldap_port String LDAP port
ldap_short_name String LDAP account ID field mapped to TeamHub login
ldap_source String LDAP sync identifier
ldap_ssl_verify Boolean false Defines whether to validate external LDAP host certificate
ldap_user String LDAP search username
license_expire_notify String 30,14,7,3 Defines the intervals (number of days) before license expiration to notify instance admins 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 Helix 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 Helix 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
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): TeamHub 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.
pilsner_timeout Integer 55 Pilsner request timeout in seconds.
redis_host String localhost Redis hostname for Cluster or HA 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 to use with Code Search and Helix Search.

Supported values:

  • Search disabled: null

  • Search enabled using Elasticsearch: elasticsearch.

  • Search enabled using Helix Search: p4search

  • Search enabled using Elasticsearch and Helix Search: elasticsearch,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 Helix 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 Helix Server connection settings.

Key Type Default Description
charset String utf8 Character set encoding on the Helix Server. For example, utf8or none.
p4port String null The hostname or IP address and port for the Helix Server, in the form of: host:port
password String null Password or ticket for the Helix Server super user
sync_interval String */5 * * * * Interval to sync with the Helix Server. Set in Cron format, default is every 5 minutes
user String null An existing Helix Server user with super level privileges. This user must have unlimited ticket timeout

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 Cluster 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 Admin user interface 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, append: ; connect-src 'self' wss://example.com;

  • example.com instance not configured to use SSL, 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 Max 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

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 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:

EECDH+ECDSA+AESGCM:EECDH+aRSA+AESGCM:EECDH+ECDSA+SHA384:EECDH+ECDSA+SHA256:EECDH+aRSA+SHA384:EECDH+aRSA+SHA256:EECDH+aRSA+RC4:EECDH:EDH+aRSA:HIGH:!RC4:!aNULL:!eNULL:!LOW:!3DES:!MD5:!EXP:!PSK:!SRP:!DSS

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

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

Key Type Default Description
es_hosts Array [] Array of Elasticsearch host hashes. Supported keys are: host, port, scheme, user, password.
es_ssl_verify Boolean true Defines whether to validate the Elasticsearch host certificate.
es_index String null Defines the Elasticsearch index name used by Helix Search.

Section: pilsner

This section groups settings related to Helix authentication.

Key Type Default Description

helix_groups_exclude_regex

String

  

Names of groups to be excluded from mirroring between Helix Server and TeamHub, specified as a comma-delimited list of Ruby regular expressions, for example:

^swarm-group$

The specified groups do not appear in the TeamHub UI.

Important

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

helix_groups_include_regex

String

  

Names of groups to be included when mirroring between Helix Server and TeamHub, specified as a comma delimited list of Ruby regular expressions, for example:

^swarm-group$

The specified groups appear in the TeamHub UI.
helix_timeout Integer 50 Helix Server request timeout in seconds.

helix_users_exclude_regex

String

 

Names of users to be excluded from mirroring between Helix Server and TeamHub, specified as a comma delimited list of Ruby regular expressions, for example:

^(user1|user2)$

The specified users do not appear in the TeamHub UI.

helix_users_from_groups_exclude_regex

String

  

Names of groups to exclude users from when mirroring between Helix Server and TeamHub, specified as a comma delimited list of Ruby regular expressions, for example:

^perforce-group$

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

helix_users_from_groups_include_regex

String

 

Names of groups to include users from when mirroring between Helix Server and TeamHub, specified as a comma delimited list of Ruby regular expressions, for example:

^perforce-group$

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

helix_users_include_regex

String

  

Names of users to be included while mirroring between Helix Server and TeamHub, specified as a comma delimited list of Ruby regular expressions, for example:

^(user1|user2)$

The specified users appear in the TeamHub UI.
host String localhost Pilsner service hostname.
port Integer 9292 Pilsner service port.

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: puma_pilsner

This section groups TeamHub Puma Pilsner server related settings.

Key Type Default Description
max_memory Integer 1000 Maximum total memory (MB) for Puma Pilsner when multiple workers are used
max_threads Integer 4 Maximum size of worker's thread pool
min_threads Integer 0 Minimum size of worker's thread pool
worker_processes Integer 2 Number of Puma Pilsner worker processes to start

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 repositories 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) 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