Skip to main content
Skip table of contents

Admin CLI

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.

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 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 section in the SignServer Reference for the given Worker and CryptoToken.

getproperty

List the value of a worker or global property.

Usage:

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

Defined Rule Set

Rule

Comment

Properties starting with id<num>.

Sets the property to the value of the given ID to the worker with the given id.

Properties starting with name<name>.

Sets the property to a worker with the given name. If the name does not exists, a unique ID will be generated and assigned.

Property keys containing GENID<NUM>, example WORKERGENID1 or GLOB. WORKERGENID1

The SignServer will find a free unique ID and assign substitute all GENID<num> with this ID.

Properties starting with glob.

Sets a global property with global scope.

Properties starting with node.

Sets a global property with node scope.

Properties starting with -<other prefix><value>

Removes the property, either worker or global.

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.

Note that 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 PKCS11 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 distinguished name and signature algorithm as parameters, and writes the request in PEM format to file. An optional key alias can be specified to generate a request given a specific key alias from the crypto token.

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

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.

CODE 
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>
Supported values for -matchSubjectWithType:

Type

Description

CERTIFICATE_SERIALNO

Serial number of the certificate.

SUBJECT_RDN_CN

Common Name (CN) RDN in textual representation from Subject DN.

SUBJECT_RDN_SERIALNO

Serial number (serialNumber/SN) RDN in textual representation from Subject DN.

SUBJECT_RDN_C

Country (C) RDN in textual representation from Subject DN.

SUBJECT_RDN_DC

Domain Component (DC) RDN in textual representation from Subject DN.

SUBJECT_RDN_ST

State or Province (ST) RDN in textual representation from Subject DN.

SUBJECT_RDN_L

Locality (L) RDN in textual representation from Subject DN.

SUBJECT_RDN_O

Organization (O) RDN in textual representation from Subject DN.

SUBJECT_RDN_OU

Organizational Unit (OU) RDN in textual representation from Subject DN.

SUBJECT_RDN_TITLE

Title (title) RDN in textual representation from Subject DN.

SUBJECT_RDN_UID

Unique ID (UID) RDN in textual representation from Subject DN.

SUBJECT_RDN_E

E-mail address in DN (E) RDN in textual representation from Subject DN.

SUBJECT_ALTNAME_RFC822NAME

RFC822Name Subject Alternative Name.

SUBJECT_ALTNAME_MSUPN

MS UPN Subject Alternative Name.

Supported values for -matchIssuerWithType:

Type

Description

ISSUER_DN_BCSTYLE

Issuer DN in textual EJBCA/BC DN style.

Usage Examples

Example 1:

CODE 
signserver authorizedclients -worker CMSSigner -list

Example 2:

CODE 
signserver authorizedclients -worker CMSSigner -add 
 -matchSubjectWithType SUBJECT_RDN_CN -matchSubjectWithValue "Client One"
 -matchIssuerWithValue "CN=AdminCA1, C=SE"

Example 3:

CODE 
signserver authorizedclients -worker CMSSigner -add 
 -matchSubjectWithType SUBJECT_RDN_CN -matchSubjectWithValue "Client One"
 -matchIssuerWithType ISSUER_DN_BCSTYLE -matchIssuerWithValue "CN=AdminCA1, C=SE" -description "my rule"

Example 4:

CODE 
signserver authorizedclients -worker CMSSigner -add 
 -matchSubjectWithType CERTIFICATE_SERIALNO -matchIssuerWithType ISSUER_DN_BCSTYLE 
 -cert /tmp/admin.pem

Example 5:

CODE 
signserver authorizedclients -worker CMSSigner -remove 
 -matchSubjectWithType CERTIFICATE_SERIALNO 
 -matchIssuerWithType ISSUER_DN_BCSTYLE 
 -cert /tmp/admin.pem

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.

Usage Examples

Usage example 1:

BASH 
signserver addauthorizedclient 1 EF34242D2324 "CN=Test Root CA"

Usage example 2:

BASH 
signserver addauthorizedclient 1 EF3456789ABC "CN=Client,O=Test Organization,C=SE"

Usage example 3:

BASH 
signserver addauthorizedclient 1 client.pem

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:

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

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

TEXT 
C=SE, O=TestOrganization, CN=IssuingCA

The following displays using escaped DN components:

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

TEXT 
CN=ReverseIssuingCA, O=TestOrganization, C=S

Alternatively, a certificate file can be specified from which the serial number and issuer DN will be taken.

Usage Examples

Usage example 1:

BASH 
signserver wsadmins -add -certserialno 123ABCDEF -issuerdn "CN=Neo Morpheus, C=SE"

Usage example 2:

BASH 
signserver wsadmins -add -cert wsadmin.pe

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. Takes an optional boolean parameter, if left out sets 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:

BASH 
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 etc) in a CryptoToken. 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:

BASH 
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 (i.e. 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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close