Preparing input parameters in a JSON file

You can create a JSON file (.json) to provide input parameters for one-touch Domino setup.

The JSON input data is organized into top-level JSON objects each corresponding to a specific component. Each top-level object can contain nested objects. For example, the serverSetup object contains the object server that includes all server-related parameters, the object network that includes all network-related parameters, and so on.

Note: The JSON file must be saved in UTF-8 format without a byte order mark (BOM) at the beginning of the file. Because UTF-8 is a superset of the ASCII character set, any file with purely printable ASCII characters is also a valid UTF-8 file.

After you've prepared the JSON file, use the validjson tool provided starting with Domino 12.0.1 to validate the configuration. For more information, see Validating the JSON configuration.

The sections in this topic includes tables that describe the supported JSON objects and parameters for the following top-level objects:
  • autoConfigPreferences, used to specify preferences.
  • serverSetup, used to set up servers and register users.
  • IDVault, used to set up an ID vault.
  • appConfiguration, used to configure applications.
An X in the First or Addt'l column of a table indicates that a parameter pertains to that type of server setup. An asterisk (*) next to an X indicates a required parameter.

The JSON file must contain valid JSON as described at json.org.

  • Value types are string unless otherwise noted. Specify strings in quotes.
  • 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.

JSON parameters for one-touch setup preferences

The following table describes parameters for the top-level object autoConfigPreferences that you use to specify preferences for running one-touch setup.
Parameter First Addt'l Description
autoConfigPreferences/deleteInputFileAfterProcessing X X If true, the input JSON file is deleted when processing is complete. This assures that confidential data such as passwords is not left on the file system. When using this option, be sure to have a backup copy of your JSON file in a secure location in case it is needed again.

Default: false
autoConfigPreferences/startServerAfterConfiguration X X If true, Domino starts after successful setup. If false, setup exits and does not start Domino.
Note: If you are using one-touch setup to configure the ID vault, leave this setting true. The Domino server must start immediately for the ID vault configuration to take effect.

Default: true
autoConfigPreferences/consoleLogOutput/show X X Specifies which one-touch setup output to write to console log. Possible values are "none", "errors", or "all".

Default: "errors"
autoConfigPreferences/consoleLogOutput/pauseOnErrorSeconds X X 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.

Default: 15

JSON parameters for server setup

The following table describes the parameters for the top-level object serverSetup that you use to set up servers with one-touch setup.
Parameter First Addt'l 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 Server title

Default: none
serverSetup/server/password X X Server ID password

Default: none
serverSetup/server/minPasswordLength X X Minimum password length for all passwords (Integer)

Default: 5
serverSetup/server/useExistingServerID X

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.

Default: false
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 A comma-separated list of server tasks that run on the server.

Default: "Replica,Router,Update,AMgr,
Adminp,Sched,CalConn,RnRMgr"
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 Value of true enables port encryption. (Boolean)

Default: true
serverSetup/network/enablePortCompression X X Value of true enables port compression. (Boolean)

Default: true
serverSetup/org/countryCode X X Organization country code

Default: none
serverSetup/org/orgName X* X* Organization name
serverSetup/org/certifierPassword X* Organization certifier
serverSetup/org/orgUnitName X X Organization unit name

Default: none
serverSetup/org/orgUnitPassword X X Organization unit password

Default: none
serverSetup/org/useExistingCertifierID X

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.

Default: false
serverSetup/org/certifierIDFilePath X

Path of certifier ID used when useExistingCertifierID is true. On Docker, the ID must be relative to the container.

Default: none
serverSetup/org/useExistingOrgUnitID X

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.

Default: false
serverSetup/org/orgUnitIDFilePath X

Path of organization unit certifier ID used when useExistingOrgUnitID is true. On Docker, the ID must be relative to the container.

Default: none
serverSetup/admin/firstName X

Administrator first name

Default: none
serverSetup/admin/middleName X

Administrator middle name or initial

Default: none
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/useExistingAdminID X

Value of true uses the existing server ID specified by IDFilePath. Default is to create a new administrator ID and save it as IDFilePath.

Default: false
serverSetup/admin/CN X*

Administrator common name, for example, "Bill Ranney."
serverSetup/notesINI/<any name> X X Any notes.ini setting can be defined when using JSON input. Use with caution when defining notes.ini settings that might be independently defined by server setup; the value defined here overrides any value previously defined by setup.

Default: none
serverSetup/security/ACL/prohibitAnonymousAccess X X Value of true gives Anonymous users No Access. (Boolean)

Default: true
serverSetup/security/ACL/addLocalDomainAdmins X X Value of true gives the LocalDomainAdmins group entry Manager access. (Boolean)

Default: true
serverSetup/security/TLSSetup/method X*

Method for creating TLS artifacts in certstore.nsf. 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

Certificate Authority display name

Default: DominoMicroCA
serverSetup/security/TLSSetup/CAOrgName X

Certificate Authority organization name. Defaults to the value of the serverSetup/org/orgName property in the source JSON file.
serverSetup/security/TLSSetup/CAKeyType X

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

Default: RSA
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/TLSKeyType X

TLSKeyType. See CAKeyType for valid values.

Default: RSA
serverSetup/security/TLSSetup/certExpirationDays X

Number of days until TLS certificate expires, an integer value between 1 and 398, inclusive.

Default: Domino chooses an appropriate value.
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

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 want data to be exportable. May use any of the indirect password mechanisms described in Specifying passwords indirectly.
serverSetup/directoryAssistance/databasePath X X Directory assistance database path. Creates the Domino Directory assistance database if necessary to be used to configure access to external LDAP directories.

Default: da.nsf
serverSetup/directoryAssistance/domainName X X Directory assistance domain name. Defaults to the value of the serverSetup/server/domainName property in the source JSON file.
serverSetup/directoryAssistance/companyName X X Directory assistance company name. Defaults to the value of the serverSetup/org/orgName property in the source JSON file.
serverSetup/directoryAssistance/LDAP/hostName X* X* DNS host name of the LDAP server.
serverSetup/directoryAssistance/LDAP/vendor X X Directory assistance LDAP vendor. Must be one of: "activeDirectory", "openLDAP", "dominoLDAP".

Default: "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 Directory assistance LDAP channel encryption. Must be "TLS" or "none".

Default: "TLS"
serverSetup/directoryAssistance/LDAP/port X X Directory assistance LDAP port.

Default:  636 for "channelEncryption": "TLS" and 389 for "channelEncryption": "none".
serverSetup/directoryAssistance/LDAP/acceptExpiredCertificates X X Directory assistance LDAP - accept expired certificates.

Default: false
serverSetup/directoryAssistance/LDAP/verifyRemoteServerCertificates X X Directory assistance LDAP - verify remote server certificates.

Default: true
serverSetup/directoryAssistance/LDAP/timeout X X Directory assistance LDAP timeout, a non-negative integer value. A value of 0 implies no timeout.

Default: 0
serverSetup/directoryAssistance/LDAP/maximumEntriesReturned X X Directory assistance LDAP maximum entries returned, a non-negative integer value. A value of 0 implies no limit.

Default: 0
serverSetup/autoregister/count X

Number of additional servers to register automatically.

Default: 0
serverSetup/autoregister/IDPath X

Specifies the directory in which to put generated server ID files. The directory must already exist. On Docker, the ID must be relative to the container.

Default: none
serverSetup/autoregister/pattern X

Specifies a pattern for the names of generated server ID files. 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.

Default: none
serverSetup/registerUsers/defaults X

An object containing default parameters for all users to register. Each individual user has properties that can override the defaults.
serverSetup/registerUsers/defaults/saveIDToPersonDocument X

If true, user ID files are saved as an attachment in the users' Person documents in the Domino directory.

Default: false
serverSetup/registerUsers/defaults/mailTemplatePath X

Path of template database to be used to create users' mail files.
serverSetup/registerUsers/defaults/password X

Password to be used for all users for which an explicit password is not provided. Use "@Prompt:" to be prompted for each user password, or specify a password to be applied to all users (recommended only for test servers). The indirect password options other than "@Prompt:" are not supported.
serverSetup/registerUsers/defaults/enableFullTextIndex X

If true, user mail databases are created with the Full Text Index database property enabled. One-touch setup does not create the indexes.

Default: false
serverSetup/registerUsers/defaults/certificateExpirationMonths X

Number of months in which users' certificates will expire.

Default: 24
serverSetup/registerUsers/users X

An array of users to register. The entire array begins with a '[' character and ends with a ']' character in the JSON input. Each entry in the array is an object that begins with a '{' character and ends with a '}' character. The properties within an object, shown below, provide the registration data for a user. Some of the properties have defaults as described in the /defaults object above.
serverSetup/registerUsers/users/firstName X

User first name
serverSetup/registerUsers/users/middleName X

User middle name
serverSetup/registerUsers/users/lastName X*

User last name
serverSetup/registerUsers/users/shortName X

User short name
serverSetup/registerUsers/users/password X

User ID file password. You can specify an explicit password or use any of the indirect password options documented in Specifying passwords indirectly. You must specify a password for each user, either with this property or with the password property within /defaults.
serverSetup/registerUsers/users/mailFilePath X

User mail file path. If not specified, a mail file is not created for the user.
serverSetup/registerUsers/users/mailTemplatePath X

Mail template path. If not specified here or with /defaults, the current Domino version's mail template is used by default.
serverSetup/registerUsers/users/IDFilePath X

User ID file path. If you also create an ID vault with one-touch setup, you can omit this property if you don't want the ID file stored on disk. In that case, one-touch setup creates a temporary ID file whose name is derived from the user's mailFilePath, if present, or a unique temporary file name. Then after uploading the ID file to the vault, one-touch setup deletes the temporary ID file. If the user ID file path is specified, the file is not deleted.
serverSetup/registerUsers/users/saveIDToPersonDocument X

If true, the user's ID file is saved as an attachment in the user's Person document in the Domino directory.
serverSetup/registerUsers/users/enableFullTextIndex X

If true, user's mail database is created with the Full Text Index database property enabled. One-touch setup does not create the index.
serverSetup/registerUsers/users/internetAddress X

User internet address. If not specified, one-touch setup uses <firstName><lastName>@<domain-name>, where <domain-name> is taken from the required property serverSetup/server/domainName.
serverSetup/registerUsers/users/certificateExpirationMonths X

Number of months in which the user's certificates will expire.
serverSetup/existingServer/CN X* Server common name, for example, "Adminserver", of the existing server to use to replicate the directory and other databases.
serverSetup/existingServer/hostNameOrIP X Server DNS host name or IP address of the existing server.

Default: none

JSON parameters for ID vault setup

The following table describes the parameters for the top-level object IDVault that you use to set up an ID vault with one-touch setup.
Parameter First Addt'l 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 X

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 file name 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

JSON parameters for application configuration

The following table describes the parameters for the top-level object appConfiguration that you use to set up applications with one-touch setup.
Parameter First Addt'l Description
appConfiguration/notesINI/<any-name> X X Any notes.ini variables may be defined here as an alternative to specifying them within serverSetup properties.
appConfiguration/databases/action X* X* Specify "create" to create a new database, or "update" to update an existing database.
appConfiguration/databases/filePath X* X* Database file path.
appConfiguration/databases/title X X Database title.
appConfiguration/databases/templatePath X X Database template file path. Required when action is "create".
appConfiguration/databases/signUsingAdminp X X When set to true, an adminp request is issued to sign all design documents using the server's ID.

Default: false
appConfiguration/databases/ACL/roles X X An array of role names. Example: [ "SpecApprover", "SpecAuthor" ]
appConfiguration/databases/ACL/ACLEntries

X

X

An array of ACL entries. The entire array begins with a '[' character and ends with a ']' character in the JSON input. Each entry in the array is an object that begins with a '{' character and ends with a '}' character. The properties within an object, shown below, provide the data for an ACL entry.
appConfiguration/databases/ACL/ACLEntries/name X* X* ACL entry name in hierarchical format (e.g. "adminserver/sherlock"). The name can be specified in canonical format (e.g. "CN=adminserver/O=sherlock") but it needn't be because one-touch setup automatically canonicalizes the name.
appConfiguration/databases/ACL/ACLEntries/level X* X* Access level. Must be one of: "noAccess", "depositor", "reader", "author", "editor", "designer", "manager".
appConfiguration/databases/ACL/ACLEntries/type X X Access type. Must be one of: "unspecified", "person", "server", "personGroup", "serverGroup", "mixedGroup"

Default: "unspecified".
appConfiguration/databases/ACL/ACLEntries/canCreateDocuments X X Named entity can create documents.

Default: false.
appConfiguration/databases/ACL/ACLEntries/canDeleteDocuments X X Named entity can delete documents.

Default: false.
appConfiguration/databases/ACL/ACLEntries/canCreatePersonalAgent X X Named entity can create private agents.

Default: false.
appConfiguration/databases/ACL/ACLEntries/canCreatePersonalFolder X X Named entity can create personal folders and views.

Default: false.
appConfiguration/databases/ACL/ACLEntries/canCreateSharedFolder X X Named entity can create shared folders and views

Default: false.
appConfiguration/databases/ACL/ACLEntries/canCreateLSOrJavaAgent X X Named entity can create LotusScript and Java agents.

Default: false.
appConfiguration/databases/ACL/ACLEntries/isPublicReader X X Named entity can read public documents.

Default: false.
appConfiguration/databases/ACL/ACLEntries/isPublicWriter X X Named entity can write public documents.

Default: false.
appConfiguration/databases/ACL/ACLEntries/canReplicateOrCopyDocuments X X Named entity can replicate and copy documents.

Default: false.
appConfiguration/databases/ACL/ACLEntries/roles X X An array of roles granted to the named entity. Example: [ "SpecApprover", "SpecAuthor" ]

Default: false.
appConfiguration/documents X X An array of documents within the database. The entire array begins with a '[' character and ends with a ']' character in the JSON input. Each entry in the array is an object that begins with a '{' character and ends with a '}' character. The properties within an object, shown below, provide the document data to be created or updated.
appConfiguration/documents/action X* X* Specify "create" to create a new document, or "update" to update an existing document.
appConfiguration/documents/findDocument X X Required when action is "update", the properties in this object define one or more items used to find the document to update. The document must have all of those items with the exact values as specified. For example: 
"findDocument": 
  { "Type": "Server", 
  "ServerName": "CN=adminserver/O=sherlock" 
}
appConfiguration/documents/computeWithForm X X Compute/Validate the document against its form. If true, form logic such as input validation formulas and default value formulas execute, possibly modifying the document (for example, adding additional items).

Default: false.
appConfiguration/documents/items X X Document items. These can be in a simple format or canonical format. You may specify some items in simple format and some in canonical format. The canonical format is required for setting any of the item flags. The simple formats are shown first, then the canonical format. The supported data types are text, number, text list, and number list.
appConfiguration/documents/items/"<item-name>": "<item-value>" X X Simple format for text item.
appConfiguration/documents/items/"<item-name>": <item-value> X X Simple format for number item. Note there are no quotes around the value.
appConfiguration/documents/items/"<item-name>": [ "v1", "v2" ] X X Simple format for text list item. Array may contain one or more items (two shown here).
appConfiguration/documents/items/"<item-name>": [ 1, 2 ] X X Simple format for number list item. Note there are no quotes around the values. Array may contain one or more items (two shown here).
appConfiguration/documents/items/"<item-name>" X X Canonical format for item
appConfiguration/documents/items/"<item-name>"/"type" X X Item data type. Optional for text and number items; may be deduced from JSON data type as with the simple formats above. If specified, must be one of: "text", "number", "datetime".
appConfiguration/documents/items/"<item-name>"/"value" X X
  • For type "text", must be either a single string or an array of strings.
  • For type "number", must be a single number or an array of numbers.
  • For type "datetime", must be a date and/or time in one of the following ISO-8601 formats, shown via examples, or an array of such values.
    • "20210728T162308,50-04" - 4 digit year, 2 digit month, 2 digit day, "T" delimiter, 2 digit hour, 2 digit minute, 2 digit second, comma delimiter, 2 digit hundredths of seconds, "+" or "-" delimiter for offset from Greenwich Mean Time, 2 digit hour timezone offset from GMT.
    • "20210728T162308,50-0330" - as above, followed by 2 digit minute timezone offset from GMT.
    • "20210728" - date only - 4 digit year, 2 digit month, 2 digit day.
    • "T162308,50" - time only - "T" delimiter, 2 digit hour, 2 digit minute, 2 digit second, comma delimiter, 2 digit hundredths of seconds.
appConfiguration/documents/items/"<item-name>"/"names" X X Item contains names.

Default: false.
appConfiguration/documents/items/"<item-name>"/"readers" X X Readers item used to determine who can read document.

Default: false.
appConfiguration/documents/items/"<item-name>"/"authors" X X Authors item used to determine who can edit document.

Default: false.
appConfiguration/documents/items/"<item-name>"/"protected" X X Item is protected.

Default: false.
appConfiguration/documents/items/"<item-name>"/"sign" X X Item is part of document signature computation if document is signed.

Default: false.
appConfiguration/documents/items/"<item-name>"/"encrypt" X X Item is encrypted if document is encrypted.

Default: false.
appConfiguration/documents/items/"<item-name>"/"nonSummary" X X Item is not a summary item. By default, items are summary items.

Default: false.
appConfiguration/agents/ X X An array of agents within the database. The entire array begins with a '[' character and ends with a ']' character in the JSON input. Each entry in the array is an object that begins with a '{' character and ends with a '}' character. The properties within an object, shown below, provide the information on the agent to be processed.
appConfiguration/agents/name X* X* Agent name.
appConfiguration/agents/action X* X* Action(s) to perform on agent. Value may be a single string or an array of strings. Valid values are:
  • "enable" - Enable the agent
  • "disable" - Disable the agent
  • "sign" - Sign the agent with the server ID
  • "run" - Run the agent