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 with Domino to validate the configuration. For more information, see Validating the JSON configuration.

The following tables describe the supported JSON objects and parameters for the following top-level objects:
  • serverSetup, used to set up servers and register users, described in Table 1.
  • IDVault, used to set up an ID vault, described in Table 2.
  • appConfiguration, used to configure applications, described in Table 3.
  • autoConfigPreferences, used to specify preferences for running one-touch setup, described in Table 4.
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.

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 server setup

Parameter First server Additional server Default Description
serverSetup: Server setup parameters:
server: Server parameters:
type X* X* Server type. Must be either:
  • "first" for first server in a Domino domain.
  • "additional" for additional servers in the domain
name X* X* Server common name, for example, "Adminserver"
domainName X* X* Domino domain name
title X X none Server title
password X X none Server ID password
minPasswordLength X X 5 Minimum password length for all passwords (Integer)
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.
IDFilePath X X* Path of server ID file. On Docker, the ID must be relative to the container.
serverTasks X X "Replica,Router,Update,AMgr,Adminp,Sched,CalConn,RnRMgr" A comma-separated list of server tasks that run on the 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.
network Network parameters:
hostName X* X* DNS host name
enablePortEncryption X X true Value of true enables port encryption. (Boolean)
enablePortCompression X X true Value of true enables port compression. (Boolean)
org: Organizational parameters:
countryCode X X none Organization country code
orgName X* X* Organization name
certifierPassword X* Organization certifier password
orgUnitName X X none Organization unit name
orgUnitPassword X X none Organization unit password
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.
certifierIDFilePath X none Path of certifier ID used when useExistingCertifierID is true. On Docker, the ID must be relative to the container.
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.
orgUnitIDFilePath X none Path of organization unit certifier ID used when useExistingOrgUnitID is true. On Docker, the ID must be relative to the container.
admin: Administration parameters:
firstName X none Administrator first name
middleName X none Administrator middle name or initial
lastName X* Administrator last name
password X* Administrator ID password
IDFilePath X* Administrator ID file path. On Docker, the ID must be relative to the container.
useExistingAdminID X false Value of true uses the existing server ID specified by IDFilePath. Default is to create a new administrator ID and save it as IDFilePath.
CN X* Administrator common name, for example, "Bill Ranney."
notesINI: notes.ini parameters: (All values must be strings)
<any name> X X none 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.
security: Security parameters:
ACL: Default database ACL entries for all new databases:
prohibitAnonymousAccess X X true Value of true gives Anonymous users No Access. (Boolean)
addLocalDomainAdmins X X true Value of true gives the LocalDomainAdmins group entry Manager access. (Boolean)
TLSSetup: Transport Layer Security setup parameters. Creates Domino certstore.nsf database and creates TLS artifacts within it
method X* Method for creating TLS artifacts. 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.
CADisplayName X DominoMicroCA Certificate Authority display name
CAOrgName X Certificate Authority organization name. Defaults to the value of the serverSetup/org/orgName property in the source JSON file.
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
CAExpirationDays X Number of days until Certificate Authority certificate expires. If not specified, Domino chooses an appropriate default.
orgName X TLS certificate organization name. Defaults to value of CAOrgName.
TLSKeyType X RSA TLSKeyType, See CAKeyType for valid values.
certExpirationDays X Number of days until TLS certificate expires, an integer value between 1 and 398, inclusive. If not specified, Domino chooses an appropriate default.
importFilePath X Required for "method": "import". Path of .pem, .p12, .pfx, or .kyr file to import.
importFilePassword X Password to decrypt import file contents. Required if import file is password protected. May use any of the indirect password mechanisms, Specifying passwords indirectly. May use any of the indirect password mechanisms as described in Specifying passwords indirectly.
retainImportFile X By default, the import file is deleted after a successful import. Specify true to retain the file.
exportPassword X Password for storing imported data encrypted, if you wish data to be exportable.
directoryAssistance: Directory assistance setup, for accessing external LDAP directories. This creates the Domino Directory assistance database if necessary, and adds a document with the specified parameters.
databasePath X X da.nsf Directory assistance database path.
domainName X X Directory assistance domain name. Defaults to the value of the serverSetup/server/domainName property in the source JSON file.
companyName X X Directory assistance company name. Defaults to the value of the serverSetup/org/orgName property in the source JSON file.
LDAP: X* X* LDAP settings
hostName X* X* DNS host name of LDAP server.
vendor X X dominoLDAP Directory assistance LDAP vendor. Must be one of: "activeDirectory", "openLDAP", "dominoLDAP".
userDN X X Directory assistance LDAP user distinguished name.
password X X Directory assistance LDAP user password.
baseSearchDN X X Directory assistance LDAP base search distinguished name.
channelEncryption X X TLS Directory assistance LDAP channel encryption. Must be "TLS" or "none".
port X X Directory assistance LDAP port. Defaults to 636 for "channelEncryption": "TLS" and to 389 for "channelEncryption": "none".
acceptExpiredCertificates X X false Directory assistance LDAP - accept expired certificates.
verifyRemoteServerCertificates X X true Directory assistance LDAP - verify remote server certificates.
timeout X X 0 Directory assistance LDAP timeout, a non-negative integer value. A value of 0 implies no timeout.
maximumEntriesReturned X X 0 Directory assistance LDAP maximum entries returned, a non-negative integer value. A value of 0 implies no limit.
autoregister: Parameters to register additional servers automatically. If not specified, you register additional servers manually.
count X 0 Number of servers to register (Integer)
IDPath X none 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.
pattern X none 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.

registerUsers: User registration data
defaults X An object containing default parameters for all the users. Each individual user has properties that can override the defaults.
saveIDToPersonDocument X false If true, user ID files are saved as an attachment in the users' Person documents in the Domino directory.
mailTemplatePath X Path of template database to be used to create users' mail files.
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.
enableFullTextIndex X false If true, user mail databases are created with the Full Text Index database property enabled. One-touch setup does not create the indexes.
certificateExpirationMonths X 24 Number of months in which users' certificates will expire.
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.
firstName X User first name
middleName X User middle name
lastName X* User last name
shortName X User short name
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.
mailFilePath X User mail file path. If not specified, a mail file is not created for the user.
mailTemplatePath X Mail template path. If not specified here or with defaults, the current Domino version's mail template is used by default.
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.
saveIDToPersonDocument X If true, the user's ID file is saved as an attachment in the user's Person document in the Domino directory.
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.
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
certificateExpirationMonths X Number of months in which users' certificates will expire.
existingServer: Parameters specifying an existing server to use to replicate the directory and other databases:
CN X* Server common name, for example, "Adminserver"
hostNameOrIP X none Server DNS host name or IP address

JSON parameters for ID vault setup

Table 1. JSON parameters for ID vault setup
Parameter First server Additional server Default Description
IDVault X ID Vault parameters. All are Required if IDVault is specified.

          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.

          description

X Vault description

          IDFile

X Vault ID file

          IDPassword

X Vault ID file password

          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"

          passwordReset:

Vault password reset parameters:

                    helpText

X Help text for users who forget their passwords

          securitySettingsPolicy:

Security Settings policy parameters:

                    name

X Security Settings policy name

                    description

X Security Settings policy description

          masterPolicy:

Master policy parameters:

                    description

X Master policy description

JSON parameters for application configuration

Table 2. JSON parameters for application configuration
Parameter First server Additional server Default Description

appConfiguration:

X X Application configuration parameters:

   notesINI:

notes.ini parameters: (All values must be strings.)

       <any-name>

X X Any notes.ini variables may be defined here as an alternative to specifying them within serverSetup properties.

   databases

X X An array of databases (applications). 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 database data to be created or updated.

      action

X* X* Specify "create" to create a new database, or "update" to update an existing database.

      filePath

X* X* Database file path.

      title

X X Database title.

      templatePath

X X Database template file path. Required when action is "create".

      signUsingAdminp

X X false When set true, an adminp request is issued to sign all design documents using the server's ID.

      ACL

X X Database ACL parameters:

            roles

X X An array of role names. Example: [ "SpecApprover", "SpecAuthor" ]

            ACLEntries

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.

                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.

               level

X* X* Access level. Must be one of: "noAccess", "depositor", "reader", "author", "editor", "designer", "manager"

               type

X X "unspecified" Access type. Must be one of: "unspecified", "person", "server", "personGroup", "serverGroup", "mixedGroup"

               canCreateDocuments

X X false Named entity can create documents.

               canDeleteDocuments

X X false Named entity can delete documents.

               canCreatePersonalAgent

X X false Named entity can create private agents.

               canCreatePersonalFolder

X X false Named entity can create personal folders and views.

               canCreateSharedFolder

X X false Named entity can create shared folders and views

               canCreateLSOrJavaAgent

X X false Named entity can create LotusScript and Java agents

                isPublicReader

X X false Named entity can read public documents.

                isPublicWriter

X X false Named entity can write public documents.

                canReplicateOrCopyDocuments

X X false Named entity can replicate and copy documents.

                roles

X X false An array of roles granted to the named entity. Example: [ "SpecApprover", "SpecAuthor" ]

      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.

         action

X* X* Specify "create" to create a new document, or "update" to update an existing document.

         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" 
} 

         computeWithForm

X X false 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).

         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.

            "<item-name>": "<item-value>"

X X Simple format for text item.

             "<item-name>": <item-value>

X X Simple format for number item. Note there are no quotes around the value.

              "<item-name>": [ "v1", "v2" ]

X X Simple format for text list item. Array may contain one or more items (two shown here).

              "<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).

             "<item-name>":

X X Canonical format for item:

                  "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".

                  "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

                   "names"

X X false Item contains names.

                  "readers"

X X false Readers item used to determine who can read document.

                  "authors"

X X false Authors item used to determine who can edit document.

                  "protected"

X X false Item is protected.

                  "sign"

X X false Item is part of document signature computation if document is signed.

                   "encrypt"

X X false Item is encrypted if document is encrypted.

                 "nonSummary"

X X false Item is not a summary item. By default, items are summary items.

      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.

         name

X* X* Agent name.

         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

JSON parameters for one-touch setup preferences

Table 3. JSON parameters for one-touch setup preferences
Parameter First server Additional server Default Description
autoConfigPreferences: One-touch setup preferences

   deleteInputFileAfterProcessing

X X false 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.

   startServerAfterConfiguration

X X true 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.

   consoleLogOutput:

X X

      show

X X "errors" Specifies which one-touch setup output to write to console log. Possible values are "none", "errors", or "all".

      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.