.png){kind=logo}
The SignServer Administration CLI (AdminCLI) is one of the available interfaces to administrate SignServer. It supports configuration of workers and associated key management as well as querying the audit log and archive.
The AdminCLI is not available for the SignServer Software Appliance deployment. For the Container deployment, only the owner can access AdminCLI. See Installation.
Using AdminCLI
The SignServer administration command line interface (AdminCLI) is started using bin/signserver (or bin/signserver.cmd for Windows).
Every Worker is identified by an ID and an optional name that can be used in all CLI commands.
You can configure a Worker while it is in production since all configuration commands are cached until a reload command is issued and the configuration becomes active. The reload command also reloads the global configuration properties. See Global Configuration Properties.
Masking of properties is applied to Admin CLI to reduce the risk of accidentally exposing sensitive data. See Masking Sensitive Properties in the Admin CLI.
The following describes the SignServer Administration CLI (AdminCLI) commands:
General Commands
Command
Description
getstatus
Returns the status of the given Worker, stating if its crypto token is active or not, and the loaded 'active' configuration. It is possible to get a brief summary or a complete listing for one Worker or all configured Workers. If all Workers are displayed, all the global configuration parameters will also be displayed.
getconfig
Returns the current Worker or global configuration depending on options. Note that for Worker configuration, this configuration might be inactive until a reload command is issued.
setproperty
Sets a custom property used by the Worker or Crypto Token. For available properties, refer to the respective page for the given Worker and Crypto Token.
getproperty
List the value of a Worker or global property.
Usage:
signserver getproperty <signerid | signerName | global | node> <propertykey>
setproperties
Used to batch a set of properties, both for the global and Worker configuration. The command can be used to configure a Signer in a test environment, dump all the properties and upload it into production.
The setproperties command reads all the configuration properties form a property file, and depending on the contents of the key, it then sets the given property. All properties are set according to the following defined rule set.
For examples, see the directory sample-configs.
removeproperty
Removes a configured property.
dumpproperties
Dumps all configured properties for one or all Workers in the system into a property file. If the configuration for one Worker is dumped, the dumpproperties tool can be used to transfer the configuration from one installation to another. If all configurations are dumped, it can be used as a backup tool.
uploadsignercertificate
Used to upload the certificate when the Worker only needs the actual signing certificate and not the entire chain.
uploadsignercertificatechain
Used when uploading a complete certificate chain to the Worker.
The correct command to use for upload depends on the Worker and Crypto Token used.
importcertificatechain
Used to import a certificate chain into a crypto token. It takes a Worker ID of the Crypto Worker (or a Worker ID of a Worker with the Crypto Token configured in the legacy way), and a path pointing to a file containing the certificate chain and a key alias to import to. Currently supported by the PKCS#11 and Keystore Crypto Token implementations.
generatecertreq
Used to generate a certificate request for a Worker to be signed by a certificate authority. The command takes a distinguished name and signature algorithm as parameters, and writes the request in PEM format to file. Optionally, you can specify a key alias to generate a request given a specific key alias from the Crypto Token. You can also add email addresses as requested Subject Alternative Name (SAN) extensions.
activatecryptotoken
Used to activate Crypto Tokens. Authentication code is usually the PIN used to unlock the keys on the HSM. Not used if the token is set to auto-activation.
deactivatecryptotoken
Brings a Crypto Token off-line. Not used if token is set to auto-activation.
renewsigner
Sends a request for renewal of the specified Worker to the specified renewal Worker. If the authcode parameter is omitted, the command will renew the certificate without an authcode, assuming the Crypto Token is auto-activated, or the Worker is using a separate Crypto Worker (recommended). To use the previous behavior of prompting for the authcode, specify the -authprompt option. When the authcode is not passed as a parameter or prompted for, an explicit activation of the token will not be performed. For more information, see Renewal Worker.
Authorization Commands
Authorization-related commands are used to configure the client authorization rules for a Worker when the Client Certificate Authorizer is used as AUTHTYPE.
Command
Description
authorizedclients
Command for adding, removing, or listing a Worker's client authorization rules. Replaces the legacy commands addauthorizedclient, removeauthorizedclient, and listauthorizedclient.
Usage: signserver authorizedclients -worker <worker name or ID> -list
signserver authorizedclients -worker <worker name or ID> <-add/-remove>
-matchSubjectWithType <SUBJECT_MATCH_TYPE> -matchSubjectWithValue <value> \
[-matchIssuerWithType <ISSUER_MATCH_TYPE>] -matchIssuerWithValue <issuer DN> \
[-description <textual description>]
signserver authorizedclients -worker <worker name or ID> <-add/-remove> \
-matchSubjectWithType <SUBJECT_MATCH_TYPE> \
[-matchIssuerWithType <ISSUER_MATCH_TYPE>] \
[-description <textual description>] \
-cert <PEM file>
addauthorizedclient
The addauthorizedclient command is deprecated and only supports legacy rules. Use the authorizedclients command instead.
Adds a client certificate to a processable Workers list of acceptable clients using this Worker. Specify certificate serial number in hex and the Issuer DN of the client certificate. If DN components contains commas, these need to be escaped with backslashes. Alternatively, a certificate file (PEM or DER format) can be specified, from which the serial number and issuer DN is fetched.
removeauthorizedclient
The removeauthorizedclient command is deprecated and only supports legacy rules. Use the authorizedclients command instead.
Removes added client certificate entries.
listauthorizedclients
The listauthorizedclients command is deprecated and only supports legacy rules. Use the authorizedclients command instead.
Displays the current list of acceptable clients.
Database Commands
Command
Description
resync
The resync command is used if a SignServer had a complete database failure. When this happens, the Global Configuration switches to Off-line mode and it is not possible for the nodes to communicate internally and the Global Configurations will no longer be in sync. When the database is up again, the resync command can be sent to the node that has the most valid Global Configuration to write it to the database. After the resynchronization is performed, the Global Configuration will re-enter On-line mode.
Archive Commands
The archive commands can be used for processable Workers with archiving enabled to find specific archived responses. Whether a Worker or Archiver supports being queried using the archive commands, is governed by their respective implementation. For Archivers other than the default OldDatabaseArchiver and Base64DatabaseArchiver, querying might have to be performed directly in a database, filesystem, or by some custom application.
Command
Description
archive findfromarchiveid
Used to extract archived data from database identified by the archive ID. The ID depends on the Worker. For example, in case of the TSA, the TimeStampInfo serial number is used. The data is stored with the same file title as the archive ID, and with the file extension depending on the type of item, for example .request or .response.
archive findfromrequestip
Used to extract all archived data requested from a specified IP address. All data is stored as separate files with the archive ID as file title, and the file extension depending on the type of item.
archive findfromrequestcert
Used to extract all archived data requested from a client by its specified certificate serial number and issuer DN. All data is stored as separate files with the archive ID as file title and the file extension depending on the type of item.
archive query
Used to query contents of the archive. Actual archived data is not fetched by this command.
Usage:
signserver archive query -limit <number> [-criteria "<field> <op> <value>" [-criteria...]] [-from <index>] [-header] [-request|-response]
|
Option |
Description |
|---|---|
|
<field> |
Field name from the archive: archiveId, requestCertSerialNumber, requestIP, requestIssuerDN, signerid, time, type. |
|
<op> |
Relational operator: GT, GE, LT, LE, EQ, NEQ, LIKE,NULL, NOTNULL. |
|
-request |
Shows only entries for requests. |
|
-response |
Shows only entries for responses. |
Examples:
signserver archive query -limit 10 -criteria "signerid EQ 1"
signserver archive query -limit 10 -criteria "signerid EQ 1" -request
signserver archive query -limit 10 -criteria "time GT 1359623137000" -criteria "requestIP EQ 127.0.0.1
signserver archive query -limit 10 -criteria "signerid EQ 1" -outpath /tmp/out\n\n"
Administrator Commands
Command
Description
wsadmins -list
Lists administrator certificates (certificate serial number and issuer DN) for administrators authorized to use the Admin Web Service interface to administrate SignServer.
wsadmins -add
Authorizes an administrator to use the Admin Web Service interface by certificate serial number (in hexadecimal) and issuer DN with space after each comma separating DN components. If DN components contains commas, these needs to be escaped with backslashes.
The following displays how to enter the issuer DN when using a certificate issued from EJBCA with the default (as specified by EJBCA) LDAP DN order:
C=SE, O=TestOrganization, CN=IssuingCA
The following displays using escaped DN components:
C=SE, O=TestOrganization\, The, CN=IssuingCA\, Th
Note that the order is reversed, compared to how the issuer DN is stored in the certificate.
The following displays how to enter the issuer DN when using a certificate issued from EJBCA with the Use LDAP DN order option disabled:
CN=ReverseIssuingCA, O=TestOrganization, C=S
Alternatively, a certificate file can be specified from which the serial number and issuer DN will be taken.
wsadmins -remove
Removes an administrator from the list of authorized administrators.
wsadmins -allowany
Specifies whether any administrator with a certificate accepted by the web server/proxy is authorized or not. When set (true), it overrides the WSADMINS global property. The property takes an optional boolean parameter. If left out, it is set to true (allow all). This can be used for initial setup.
Auditor Commands
Command
Description
wsauditors -list
Lists auditor certificates (certificate serial number and issuer DN) for administrators authorized to use the Admin Web Service interface to query the audit log of SignServer.
wsauditors -add
Authorizes an auditor to use the Admin Web Service interface by certificate serial number (given in hexadecimal) and issuer DN.
wsauditors -remove
Removes an auditor from the list of authorized administrators.
Archive Auditor Commands
Command
Description
wsarchiveauditors -list
Lists archive auditor certificates (certificate serial number and issuer DN) for auditors authorized to use the Admin Web Service interface to query the archive of SignServer.
wsarchiveauditors -add
Authorizes an auditor, by specifying a certificate serial number (in hexadecimal) and issuer DN, to use the Admin Web Service interface for querying the archive.
wsarchiveauditors -remove
Removes an auditor from the list of authorized archive auditors.
auditlog -query
Query the CESeCore audit log.
Usage:
signserver auditlog -query -limit <number> [-criteria "<field> <op> <value>" [-criteria...]] [-from <index>] [-header]
|
Option |
Description |
|---|---|
|
-limit |
Sets the maximum number of rows matched. Required to avoid putting too much load on the server. |
|
<field> |
Field name from the audit log: additionalDetails, authToken, customId, eventStatus, eventType, module, nodeId, searchDetail1, searchDetail2, sequenceNumber, service, timeStamp. |
|
<op> |
Relational operator: GT, GE, LT, LE, EQ, NEQ, LIKE, NULL, NOTNULL. |
|
-from |
Lower index in search result (0-based). |
|
-header |
Outputs a column header before the results. |
If databaseprotection.enableverify is enabled at the server side, the signature of each row displayed is verified. If the verification fails for any of the rows matching the search criteria, an error message is displayed. The error message contains information about the first row that failed.
querytokenentries
Queries the entries (key alias, certificates) in a Crypto Token. If no limit is given, all entries are queried and printed (10 at a time). You can specify to start query from an index in the result. Search conditions can be added to only search for entries with certain key aliases.
Usage:
signserver querytokenentries -token <id or name> -limit <number> [-criteria "<field> <op> <value>" [-criteria...]] [-from <index>] [-v]
|
Option |
Description |
|---|---|
|
-limit |
Sets the maximum number of rows matched. Required to avoid putting too much load on the server. |
|
<field> |
Field name from the token: alias. |
|
<op> |
Relational operator: EQ, NEQ or LIKE. |
|
-v |
Means verbose and if given, the output also includes type, as well as any certificates or additional information available in each entry. |
Peer Systems Commands
Command
Description
wspeersystems -list
Lists certificates (certificate serial number and issuer DN) for peer systems, such as EJBCA, authorized to use the Peer Systems interface to query available key bindings and perform certificate renewal/rekeying.
wspeersystems -add
Authorizes a peer system to use the Peer Systems interface by certificate serial number (given in hexadecimal) and issuer DN.
wspeersystems -remove
Removes a peer system from the list of authorized peer systems.
Status Repository Commands
The status repository holds non-persistent local (per JVM) status information (properties) with optional expiration times. After the expiration time, the property is not returned. The value is also not preserved among server restarts.
The status repository can be controlled using following properties:
Command
Description
getstatusproperty
Gets the value of the status property. Execute the getstatusproperty command with the property name.
getstatusproperties
Gets the value of all status properties and their expiration time.
setstatusproperty
Sets the status property TIMESOURCE0_INSYNC to true.
For more information, see Status Repository.
Masking Sensitive Properties in Admin CLI
Masking of properties is applied to Admin CLI to reduce the risk of accidentally exposing sensitive data, for instance when sharing outputs for troubleshooting or support purposes, certain property values can be masked when exporting Worker configurations or displaying the Worker status, and so on.
By default, the following properties are masked:
-
PIN
-
KEYSTOREPASSWORD
-
KEYDATA
Masking is enforced for commands executed in the local Admin CLI when retrieving properties from the server.
The Admin CLI also supports masking when reading in configuration and setting properties. To configure masking for those commands, use the admincli.maskedworkerproperties property in the conf/signserver_cli.properties file.
In the SignServer Software Stack deployment, you can customize which properties are masked by setting the maskedworkerproperties parameter in the conf/signserver_deploy.properties file at deployment time. Refer to the sample configuration file for examples. See the Configure Deployment section in Install SignServer for details on how to apply these settings.