Preparing input parameters through system environment variables

As an alternative to using a JSON file, you can use system environment variables to provide input parameters for one-touch Domino setup.

If you run Domino on Docker, you define the system environment variables for Docker to export in a text file specified by the --env-file parameter. If you run Domino on Windows or UNIX, after you install Domino, you use a batch file or shell script or run individual commands to export the system environment variables needed to set up your server. The syntax for the export command varies but an example using the bash shell on Linux is: 
export SERVERSETUP_SERVER_TYPE=additional
The names of the system environment variables are similar to the parameter names specified in a JSON file, with the following exceptions:
  • On platforms where names are case-sensitive, for example UNIX, you must specify system environment variables names in uppercase.
  • Whereas the JSON input is hierarchical in nature, environment variables are in a "flat" or global namespace. Therefore, you form the names by inserting an underscore between names to indicate hierarchy. For example, A JSON input file might provide the following data: 
    "serverSetup": {
		"server": {
			"type": "additional",
			"name": "mailserver1",
			"domainName": "Renovations",
			"title": "Renovations Mail Server"
		},
    The corresponding system environment variables defined in an --env-file specified to Docker would be as follows:
    Note: When using --env-file, do not put the values in quotes. 
    SERVERSETUP_SERVER_TYPE=additional
SERVERSETUP_SERVER_NAME=mailserver1
SERVERSETUP_SERVER_DOMAINNAME=Renovations
SERVERSETUP_SERVER_TITLE=Renovations Mail Server
    The corresponding system environment variables defined in a UNIX bash shell script would be as follows. You invoke the shell script within the same shell that invokes one-touch Domino Setup. In this case, only values that contain spaces require quotes; using quotes for other values is optional. The quotes are stripped from the values when the script runs.
    export SERVERSETUP_SERVER_TYPE=additional
export SERVERSETUP_SERVER_NAME=mailserver1
export SERVERSETUP_SERVER_DOMAINNAME=Renovations
export SERVERSETUP_SERVER_TITLE="Renovations Mail Server"
The following tables describe supported system environment variables for server setup, ID vault, and one-touch setup preferences.
  • An X in the First server or Additional server column indicates that a parameter pertains to that type of server setup.
  • An asterisk (*) next to an X indicates a required parameter.
  • Value types are string unless otherwise noted.
  • Note the following rules related to putting quotes around string values:
    • When specifying in a file through the Docker --env-file argument, quotes are not allowed.
    • When specifying through a Windows batch file, quotes are not required.
    • When specifying through a UNIX bash shell script, quotes are required around strings that contain spaces. Otherwise, quotes are not required. For example, specify export SERVERSETUP_SERVER_TITLE="ACME Application Server" and not export SERVERSETUP_SERVER_TITLE=ACME Application Server.
  • Boolean values are indicated by true or false without quotes.
  • Numeric values are specified without quotes except when they function as strings, such as notes.ini values.
  • To apply a default value, specify null without quotes or omit the parameter.

System environment variables for server setup

Table 1. System environment variables for server setup
Variable First server Additional server Default Description
SERVERSETUP_SERVER_TYPE X* X* Server type. Must be either:
  • first for first server in a Domino domain.
  • additional for additional servers in the domain.
SERVERSETUP_SERVER_NAME X* X* Server common name, for example, Adminserver.
SERVERSETUP_SERVER_DOMAINNAME X* X* Domino domain name
SERVERSETUP_SERVER_TITLE X X None Server title
SERVERSETUP_SERVER_PASSWORD X None Server ID password
SERVERSETUP_SERVER_MINPASSWORDLENGTH X X 5 Minimum password length for all passwords. (Integer)
SERVERSETUP_SERVER_USEEXISTINGSERVERID X false Value of true uses the existing server ID specified by IDFilePath. Default is to create a new server ID that defaults to server.id in the Domino data directory
SERVERSETUP_SERVER_IDFILEPATH X X* Path of server ID file. On Docker, the ID must be relative to the container.
SERVERSETUP_SERVER_SERVERTASKS X X "Replica,Router,Update,AMgr,Adminp,Sched,CalConn,RnRMgr" A comma-separated list of server tasks that run on the server.
SERVERSETUP_SERVER_ADDITIONALSERVERTASKS X X A comma-separated list of additional tasks to run on the server. Use this to add to the default list of server tasks.
SERVERSETUP_NETWORK_HOSTNAME X* X* DNS host name
SERVERSETUP_NETWORK_ENABLEPORTENCRYPTION X X true Value of true enables port encryption. (Boolean)
SERVERSETUP_NETWORK_ENABLEPORTCOMPRESSION X X true Value of true enables port compression. (Boolean)
SERVERSETUP_ORG_COUNTRYCODE X X None Organization country code
SERVERSETUP_ORG_ORGNAME X* X* Organization name
SERVERSETUP_ORG_CERTIFIERPASSWORD X* Organization certifier password
SERVERSETUP_ORG_ORGUNITNAME X X None Organization unit name
SERVERSETUP_ORG_ORGUNITPASSWORD X X None Organization unit password
SERVERSETUP_ORG_USEEXISTINGCERTIFIERID X false Value of true uses the existing certifier ID specified by certifierIDFilePath. Default is to create a new certifier ID that defaults to cert.id in the Domino data directory. On Docker, the ID must be relative to the container.
SERVERSETUP_ORG_CERTIFIERIDFILEPATH X None Path of certifier ID used when useExistingCertifierID is true. On Docker, the ID must be relative to the container.
SERVERSETUP_ORG_USEEXISTINGORGUNITID X false Value of true uses the existing organization unit certifier ID specified by orgUnitIDFilePath. Default when an orgUnitName is specified is to create a new organization unit certifier ID that defaults to oucert.id in the Domino data directory. On Docker, the ID must be relative to the container.
SERVERSETUP_ORG_ORGUNITIDFILEPATH X none Path of organization unit certifier ID used when useExistingOrgUnitID is true. On Docker, the ID must be relative to the container.
SERVERSETUP_ADMIN_FIRSTNAME X None Administrator first name
SERVERSETUP_ADMIN_MIDDLENAME X None Administrator middle name or initial
SERVERSETUP_ADMIN_LASTNAME X* Administrator last name
SERVERSETUP_ADMIN_PASSWORD X* Administrator ID password
SERVERSETUP_ADMIN_IDFILEPATH X* Administrator ID file path. On Docker, the ID must be relative to the container.
SERVERSETUP_ADMIN_CN X* Administrator common name.
SERVERSETUP_SECURITY_ACL_PROHIBITANONYMOUSACCESS X X true Value of true gives Anonymous users No Access in the ACL of all new databases. (Boolean)
SERVERSETUP_SECURITY_ACL_ADDLOCALDOMAINADMINS X X true Value of true gives the LocalDomainAdmins group entry Manager access in the ACL of all new databases. (Boolean)
SERVERSETUP_SECURITY_TLSSETUP_METHOD X* Method for creating TLS artifacts certstore.nsf database. Must be one of:
  • "dominoMicroCA" to create a Domino Micro Certificate Authority and use it to create a TLS certificate. Valid parameters are CADisplayName, CAOrgName, CAKeyType, CAExpirationDays, orgName, TLSKeyType, certExpirationDays.
  • "import" to import certificate data from a .pem, .p12, .pfx, or .kyr file. Valid parameters are importFilePath, importFilePassword, retainImportFile, exportPassword.
SERVERSETUP_SECURITY_TLSSETUP_CADISPLAYNAME X DominoMicroCA Certificate Authority display name.
SERVERSETUP_SECURITY_TLSSETUP_CAORGNAME X Certificate Authority organization name. Defaults to the value of the SERVERSETUP_ORG_ORGNAME system environment variable.
SERVERSETUP_SECURITY_TLSSETUP_CAKEYTYPE X RSA Certificate Authority key type. Must be one of:
  • "RSA" - RSA with default key size
  • "ECDSA" - ECDSA with default key size
  • "RSA2048" - RSA with 2048 bit key
  • "RSA4096" - RSA with 4096 bit key
  • "ES256" - ECDSA with 256 bit key "ES384" - ECDSA with 384 bit key.
SERVERSETUP_SECURITY_TLSSETUP_ CAEXPIRATIONDAYS X Number of days until Certificate Authority certificate expires. If not specified, Domino chooses an appropriate default.
SERVERSETUP_SECURITY_TLSSETUP_ ORGNAME X TLS certificate organization name. Defaults to value of CAORGNAME.
SERVERSETUP_SECURITY_TLSSETUP_TLSKKEYTYPE X RSA See CAKEYTYPE for valid values.
SERVERSETUP_SECURITY_TLSSETUP_CERTEXPIRATIONDAYS X Number of days until TLS certificate expires, an integer value between 1 and 398, inclusive. If not specified, Domino will choose an appropriate default.
SERVERSETUP_SECURITY_TLSSETUP_IMPORTFILEPATH X Required for "method": "import". Path of .pem, .p12, .pfx, or .kyr file to import.
SERVERSETUP_SECURITY_TLSSETUP_IMPORTFILEPASSWORD X Password to decrypt import file contents. Required if import file is password protected. May use any of the indirect password mechanisms as described in Specifying passwords indirectly.
SERVERSETUP_SECURITY_TLSSETUP_RETAINIMPORTFILE X false By default, the import file is deleted after a successful import. Specify true to retain the file.
SERVERSETUP_SECURITY_TLSSETUP_EXPORTPASSWORD X Password for storing imported data encrypted, if you wish data to be exportable.
SERVERSETUP_DIRECTORYASSISTANCE_DATABASEPATH X X da.nsf Directory assistance database path. Creates a directory assistance database.
SERVERSETUP_DIRECTORYASSISTANCE_DOMAINNAME X X Directory assistance domain name for an LDAP directory. Defaults to the value of the SERVERSETUP_SERVER_DOMAINNAME.
SERVERSETUP_DIRECTORYASSISTANCE_COMPANYNAME X X Directory assistance company name. Defaults to the value of SERVERSETUP_ORG_ORGNAME.
SERVERSETUP_DIRECTORYASSISTANCE_LDAP_HOSTNAME X* X* DNS host name of the LDAP server.
SERVERSETUP_DIRECTORYASSISTANCE_LDAP_VENDOR X X dominoLDAP Directory assistance LDAP vendor. Must be one of: "activeDirectory", "openLDAP", "dominoLDAP".
SERVERSETUP_DIRECTORYASSISTANCE_LDAP_USERDN X X Directory assistance LDAP user distinguished name.
SERVERSETUP_DIRECTORYASSISTANCE_LDAP_PASSWORD X X Directory assistance LDAP user password.
SERVERSETUP_DIRECTORYASSISTANCE_LDAP_BASESEARCHDN X X Directory assistance LDAP base search distinguished name.
SERVERSETUP_DIRECTORYASSISTANCE_LDAP_CHANNELENCRYPTION X X TLS Directory assistance LDAP channel encryption. Must be "TLS" or "none".
SERVERSETUP_DIRECTORYASSISTANCE_LDAP_PORT X X Directory assistance LDAP port. Defaults to 636 for SERVERSETUP_DIRECTORYASSISTANCE_LDAP_CHANNELENCRYPTION=TLS and to 389 for SERVERSETUP_DIRECTORYASSISTANCE_LDAP_CHANNELENCRYPTION=none.
SERVERSETUP_DIRECTORYASSISTANCE_LDAP_ACCEPTEXPIREDCERTIFICATES X X false Directory assistance LDAP - accept expired certificates.
SERVERSETUP_DIRECTORYASSISTANCE_LDAP_VERIFYREMOTESERVERCERTIFICATES X X true Directory assistance LDAP - verify remote server certificates.
SERVERSETUP_DIRECTORYASSISTANCE_LDAP_TIMEOUT X X 0 Directory assistance LDAP timeout, a non-negative integer value. A value of 0 implies no timeout.
SERVERSETUP_DIRECTORYASSISTANCE_LDAP_MAXIMUMENTRIESRETURNED X X 0 Directory assistance LDAP maximum entries returned, a non-negative integer value. A value of 0 implies no limit.
SERVERSETUP_AUTOREGISTER_COUNT X 0 Number of servers to register automatically. (Integer) If you don't use autoregister, you register servers manually.
SERVERSETUP_AUTOREGISTER_IDPATH X None Specifies the directory in which to put generated server ID files if you register servers automatically. The directory must already exist. On Docker, the IDs must be relative to the container.
SERVERSETUP_AUTOREGISTER_PATTERN X None Specifies a pattern for the names of generated server ID files if you register servers automatically. Pattern must contain a single '#' character which will be replaced with the numbers 0, 1, ... up to count-1.

For example, if count is 3 and pattern is mailserver#, the resulting ID files are named mailserver0.id, mailserver1.id, mailserver2.id.
SERVERSETUP_EXISTINGSERVER_CN X* Server common name of an existing server from which to replicate the Domino directory and other databases, for example, Adminserver.
SERVERSETUP_EXISTINGSERVER_HOSTNAMEORIP X None Server DNS host name or IP address of the existing server.

System environment variables for ID vault

Note: ID vault setup is optional, but if specified, all variables are required.
Table 2. System environment variables for ID vault
Variable First server Additional server Default Description
IDVAULT_NAME X Vault name. Specify as "O=<vaultname>" for example, "O=DemoVault". You must include the "O=" prefix. If you omit it, you can get an 'Entry not found in index' error when the vault creation is attempted.
IDVAULT_DESCRIPTION X Vault description
IDVAULT_IDFILE X Vault ID file
IDVAULT_IDPASSWORD X Vault ID file password
IDVAULT_PATH Vault database path. This is an optional parameter and we recommend you not specify it since it can be derived from the name parameter. If you do specify it, the directory portion of the path must be IBM_ID_VAULT and the filename portion of the path must match the name parameter, without the O= prefix, for example, "IBM_ID_VAULT/DemoVault.nsf"
IDVAULT_PASSWORDRESET_HELPTEXT X Help text for users who forget their passwords
IDVAULT_SECURITYSETTINGSPOLICY_NAME X Security Settings policy name
IDVAULT_SECURITYSETTINGSPOLICY_DESCRIPTION X Security Settings policy description
IDVAULT_MASTERPOLICY_DESCRIPTION X Master policy description

System environment variables for one-touch setup preferences

Table 3. System environment variables for one-touch setup preferences
Variable First server Additional server Default Description
AUTOCONFIGPREFERENCES_STARTSERVERAFTERCONFIGURATION X X true If true, Domino starts after successful setup. If false, setup exits and does not start Domino.
AUTOCONFIGPREFERENCES_CONSOLELOGOUTPUT_SHOW X X "errors" Specifies which one-touch setup output to write to console log. Possible values are "none", "errors", or "all".
AUTOCONFIGPREFERENCES_CONSOLELOGOUTPUT_PAUSEONERRORSECONDS X X 15 Time to pause (in seconds) before exiting when one-touch setup completes with error. Note that for certain errors that happen early in the setup process, there is no pause. You can always consult IBM_TECHNICAL_SUPPORT/autoconfigure.log for output.