Evoke command reference

This reference describes currently-supported commands for the Conjur Evoke configuration utility.

Backup

Creates an encrypted back up of the Conjur Server, that contains both the archive and the encryption key needed to unlock the archive.

evoke backup

This command outputs both the archive and its encryption key to /opt/conjur/backup.

CA

Certificate authority related commands.

Import

Import a certificate generated by a third-party CA. If the file argument is - then the certificate is read from stdin.

evoke ca import [command options] cert-file

Options

Flag	Description	Default
`-f, --[no-]force`	Force potentially destructive operations.	Potentially destructive operations are not forced.
`-k, --key=arg`	Optional path to the key to import.	The key is not imported.
`-r, --[no-]root`	Import a root certificate (chain).	The root certificate (chain) is not imported.
`--[no-]restart`	Restart services after processing.	The services are restarted.
`-s, --[no-]set`	Set as the TLS certificate of this host.	The imported certificate is not set as the TLS certificate of this host.

Issue

Issue a new certificate.

evoke ca issue [command options] [altname ...]

Options

Flag	Description	Default
`-f, --[no-]force`	Force potentially destructive operations.	Potentially destructive operations are not forced.

Regenerate

Regenerate the Leader certificate, for example, to add new altnames. This command is applicable to self-signed certificates only. For more information, see Self-signed certificates.

evoke ca regenerate [command options] [altname ...]

Options

Flag	Description	Default
`-f, --[no-]force`	Force potentially destructive operations.	Potentially destructive operations are not forced.
`-r, --[no-]replace`	Replace altnames instead of adding new ones.	Existing altname is unchanged.
`--[no-]restart`	Restart services after processing.	The services are restarted.

Audit forwarding

Manage Follower certificates for audit forwarding authentication.

Add

Add a trusted Follower certificate by DNS name. The certificate must be already imported with evoke ca import.

evoke audit-forward add [command options] dns-name

Options

Flag	Description	Default
`--replace`	Remove any existing certificates with the same DNS name.	Existing certificates are not removed.
`--force`	Force removal of existing certificates.	Existing certificates are not forcibly removed.

List

Print the trusted Follower certificate fingerprints.

evoke audit-forward list [command options]

Options

Flag	Description	Default
`-d, --dns-name=dns_name`	The DNS name of the Follower.	None
`--fingerprint=fingerprint`	SHA-1 fingerprint.	None

Remove

Remove a trusted Follower certificate by either DNS name or SHA-1 fingerprint.

evoke audit-forward remove [command options]

Options

Flag	Description	Default
`-d, --dns-name=dns_name`	The DNS name of the Follower.	None
`--fingerprint=fingerprint`	SHA-1 fingerprint.	None
`--[no-]force`	Force removal of multiple matches	Multiple matches are not removed.

Conjur cluster

Conjur cluster commands.

Enroll

Enroll this node in the named Conjur cluster.

evoke cluster enroll [command options] <cluster-name>

Options

Flag	Description	Default
`-m, --master-name=master-name`	Name of the Conjur cluster Leader.	The cluster Leader is used from the seed file.
`-n, --cluster-machine-name=name`	Name for this machine in the Conjur cluster.	Value from the `CLUSTER_MACHINE_NAME` environment variable, if present, or the `hostname` reported by the operating system, as identified with the command `uname --nodename`.
`-r, --[no-]reenroll`	Re-enroll this machine in the Conjur cluster.	The node is not re-enrolled.

Member

Commands for managing auto-failover Conjur cluster members.

Add

Add a member to the current auto-failover Conjur cluster.

evoke cluster member add <cluster-machine-name>

List

List members of the current auto-failover Conjur cluster.

evoke cluster member list

Remove

Remove a member from the current auto-failover Conjur cluster, by name or auto-failover cluster member id.

evoke cluster member remove <machine-name-or-id>

Configuration

Commands to manage node configuration settings in the conjur.yml file.

For more information on how Conjur applies configuration settings, see Manage Conjur configuration.

Theconfig.yml file currently allows you to configure trusted proxies and authenticators only. Support for addtional features will be added in future releases.

Apply

Run this command to apply configuration settings in the conjur.yml file. This command must be run on each node.

evoke configuration apply [command options]

Options

Flag

Description

Default

--help

Displays help for this command.

Help is not displayed.

-t, --test

Verifies only the correct syntax of configuration variables. The following codes are returned:

Zero (0) indicates no errors were found.

One (1) indicates an error was found, which is returned and a message is printed to the console.

When done, run this command again, without –-test, to apply configuration settings and restart services.

Configuration variables are applied without running a test.

Show

Run this command to view a list of configuration settings and values, including the source where the applied configuration originated.

Since this command pulls the current settings from environment variables and the configuration file, the settings displayed do not reflect the current run state of nodes. This is because a new configuration could have been updated, but not yet applied to a node.

evoke configuration show [command options]

Options

Flag	Description	Default
`--help`	Displays help for this command.	Help is not displayed.
`-o, --output=<output>`	Format of output can be either: json or text.	Text

Declare nodes

Commands to configure a Conjur node to operate as a Leader, Follower, or Standby. These commands are run once, when you set up a new node. The command installs the necessary files into the correct locations and starts the system processes that comprise a Leader, Follower, or Standby node.

Master

Configures a Conjur Leader.

evoke configure master [command options] <organization-account>

Options

Flag	Description	Default
`--accept-eula`	Accept the CyberArk EULA.	Interactively prompt for EULA.
`--follower-altnames=name1,name2`	Alternative DNS names for Followers, separated by commas.	Additional alternative names are not specified.
`--internal-account`	Set the name for the Leader internal system account. We do not recommend using this account to configure the Conjur Leader.	system
`-h, --hostname=hostname`	Hostname `--hostname` is a required flag. If a value is not specified, you receive the following error message: `error: Hostname can't be empty` Domain names can contain a maximum of 63 characters.	n/a
`-j, --json-attributes-file=filename`	Extended JSON attributes.	Extended attributes from a JSON file are not used.
`--master-altnames=name1,name2`	Alternative DNS names for the Leader, comma-separated.
`-p, --admin-password=password`	Password for `admin` user. `--admin` is a required flag. If a value is not specified, you receive the following error message: `error: Admin password can't be empty`	n/a

Follower

Configures a Conjur Follower.

evoke configure follower [command options]

Options

Flag	Description	Default
`-j, --json-attributes-file=filename`	Extended JSON attributes.	Extended attributes from a JSON file are not used.
`-p, --master-port=port`	Leader port.	443

Standby

Configures a Conjur Standby.

evoke configure standby [command options]

Options

Flag	Description	Default
`-a, --master-address=address`	Leader address.	The Leader address from the seed file is not used.
`-i, --master-ip=master-ip`	Leader IP address. This option is deprecated. Use `--master-address` instead.	The Leader address from the seed file is not used.
`-j, --json-attributes-file=filename`	Extended JSON attributes.	Extended attributes from a JSON file are not used.
`-p, --master-port=port`	Leader port.	443

EULA

Display the CyberArk Software End User License Agreement (EULA).

Show

Print the EULA content to the terminal.

evoke eula show

Help

Shows a list of commands or help for one command. Provides help for the application or its commands. Can also list the commands in a way that is helpful to creating a bash-style completion function.

evoke help [command options] command

Options

Flag	Description	Default
`-c`	Lists commands, one per line, to assist with shell completion.	Show full command help.

Keys

Commands to lock and unlock server keys.

Decrypt

Decrypt a server key.

The optional master-key-file command argument is either a file that contains the 32-byte binary master key, or the dash - character, which signifies that the master key should be read from stdin. The master key can also be obtained automatically from a configured facility.

evoke keys decrypt key-name master-key-file?

Decrypt all

Decrypts all the encrypted key material and restores the plain text files.

The optional master-key-file command argument is either a file which contains the 32-byte binary master key, or the dash - character, which signifies that the master key should be read from stdin. The master key can also be obtained automatically from a configured facility.

evoke keys decrypt-all master-key-file?

Encrypt

Encrypt the server keys.

When the keys are encrypted, the server keys are replaced with their encrypted counterparts. The master key can subsequently be used to unlock the server keys and make them available to the Conjur service. If the master key is lost, the server keys are lost as well and the encrypted data is irrevocably lost.

evoke keys encrypt master-key-file?

Exec

Run a child process with the unlocked keys in the keyring.

evoke keys exec [command options] master-key-file? -- command [arg1, arg2 ...]

Options

Flag	Description	Default
`-m, --[no-]propagate-master-key`	Propagate the master key itself, as the `master-key` key.	The master key is not propagated.

KMS

Commands to manage AWS KMS ciphertextBlobs for master key encryption. For more information, see Encrypt the master key using AWS KMS.

Set

Write the KMS ciphertextBlob to the local file system.

evoke keys kms set --region [--force] [--validate] ciphertextblob

Flag	Description	Default
`--region`	The AWS region to which the KMS CMK belongs.	n/a
`ciphertextblob?`	A file containing the base64-encoded ciphertextBlob, or the dash `-` character, which signifies the base64-encoded ciphertextBlob should be read from stdin.	n/a
`[--force]`	Optional flag that overwrites the existing ciphertextBlob.	n/a
`[--validate]`	Optional flag that verifies the node is able to decrypt the ciphertextBlob prior to writing it to the file system.	n/a

Delete

Delete a KMS ciphertextBlob from the file system for a specific region.

evoke keys kms delete --region

Flag	Description	Default
`--region`	The AWS region to which the KMS CMK belongs.	n/a

List

List all the KMS ciphertextBlob on the local file system.

evoke keys kms list

Validate

Validate that the KMS ciphertextBlob can be decrypted.

evoke keys kms validate --region

Flag	Description	Default
`--region`	The AWS region to which the KMS CMK belongs.	n/a

Lock

Lock the server keys.

This command revokes the decrypted server keys from the conjur kernel keyring.

evoke keys lock

Show master key

Obtain and print the master key.

In certain scenarios, the master key can be obtained automatically (for example from an HSM or Amazon KMS). This command attempts to retrieve and print the master key.

evoke keys show-master-key

Unlock

Unlock the server keys.

This command should be performed after evoke keys encrypt. It accepts the master key (from HSM, KMS, file or stdin for -), and decrypts the keys and places them into the conjur kernel keyring. This enables the Conjur services to access the decrypted keys and start up.

The optional master-key-file command argument is either a file that contains the 32-byte binary master key, or the dash- character, which signifies that the master key should be read from stdin. The master key can also be obtained automatically from a configured facility.

evoke keys unlock master-key-file?

Options

Flag	Description	Default
`--[no-]restart`	Avoid restarting services after processing.	The services are left in their current state.

PKCS11

PKCS#11 token configuration.

Generate

Generate a master key wrapping key.

Generate a new master key wrapping key in the configured PKCS#11 token. For convenience, the token is initialized if required.

evoke pkcs11 generate

Status

Show PKCS#11 status.

Print details about the configured PKCS#11 library, token and wrapping key, and check whether a matching wrapped master key can be found.

evoke pkcs11 status

Wrap

Wrap the master key.

Wrap the Conjur master key using configured PKCS#11 token and key. The Conjur master key can be obtained by other mechanisms or it can be generated.

evoke pkcs11 wrap [command options] [(master-key-file | STDIN)]

Options

Flag	Description	Default
`-g, --[no-]generate`	Force generation of a new master key, even if one can be found.	A new master key is not generated.
`--[no-]no-generate`	Prevent generation of a new master key, even if none can be found.	A new master key is generated if one cannot be found.

Proxy

To maintain backwards compatibility, we continue to support the evoke proxy command set. However, the evoke proxy command set has been deprecated and will be removed in a future release. If you use these commands, you'll receive a message on the console. We strongly recommend configuring trusted proxies in the conjur.yml file.For more information, see Manage Conjur configuration

When Conjur receives an incoming HTTP request, it examines the client's IP address. By default, if this address is non-routable, it is assumed to come from a proxy or load balancer. You can change this behavior by changing the address ranges that are considered non-routable.

Add

Add one or more trusted proxy CIDRs.

evoke proxy add [command options] cidr...

Options

Flag	Description	Default
`-q, --quiet`	Don't print informational messages.	Informational messages are printed.
`--[no-]restart`	Restart services after processing.	Services are restarted.

List

List trusted proxy CIDRs.

evoke proxy list [command options]

Options

Flag	Description	Default
`-q, --quiet`	Don't print informational messages.	Services are restarted.

Remove

Remove one or more trusted proxy CIDRs.

evoke proxy remove [command options] cidr...

Options

Flag	Description	Default
`-q, --quiet`	Don't print informational messages.	Informational messages are printed.
`--[no-]restart`	Restart services after processing.	Services are restarted.

Unset

Unset all trusted proxy CIDRs, returning to the default behavior.

evoke proxy unset [command options]

Options

Flag	Description	Default
`--[no-]restart`	Restart services after processing.	Services are restarted.

Replication

Server replication commands.

Rebase

Change the replication Leader.

Switches the replication Leader of this machine. The new Leader is indicated by the master-ip argument. In order for this operation to succeed, the new Leader must be running a compatible Postgres timeline, and its replication log must not be behind this machine.

To test whether a particular Leader is a valid replication Leader, use the --dry-run flag.

evoke replication rebase [command options] master-ip

Options

Flag	Description	Default
`--[no-]dry-run`	Check whether the machine identified by the `master-ip` argument is a valid replication Leader for this server.	A dry run does not occur.

Stop

Stop replicating.

evoke replication stop

Sync

Control the use of synchronous replication.

Disable

Disable synchronous replication on this standby.

When synchronous replication is disabled on a standby, it is not eligible to be selected as the synchronous standby. When synchronous replication is started on the Leader, this standby will never be chosen.

evoke replication sync disable

Enable

Enable synchronous replication on this standby.

When synchronous replication is enabled on a standby, it is eligible to be selected as the synchronous standby when synchronous replication is started on the Leader.

evoke replication sync enable

Start

Start synchronous replication. Switches the replication mode to synchronous replication.

In synchronous replication mode, the server commits all changes to at least one replica before responding. For this reason, a standby is required for this mode. At least two standbys are recommended, as losing the last standby in synchronous mode renders the server unable to handle requests.

You can use the --force option to switch into synchronous mode even if only one standby is present.

evoke replication sync start [command options]

Flag	Description	Default
`-f`, `--[no-]force`	Force to synchronous mode even when too few standbys are present.	Synchronous mode is not forced if there are too few standbys.

Stop

Stop synchronous replication. Switches the replication mode to asynchronous replication, which is the default setting.

In asynchronous replication mode, the server doesn't wait for a replica to synchronize before responding. This means if the server goes down in the meantime, there could be changes that haven't been replicated but have been confirmed to a client.

evoke replication sync stop

Replication set

Provides basic operations for replication sets.

Create

Create a new replication set for use in data segregation per Follower.

Replication set names can contain a maximum of 42 characters.

evoke replication-set create <replication-set-name>

Delete

Deletes the specified replication set.

evoke replication-set delete [command options] <replication-set-name>

Options

Flag	Description	Default
`-f` , `--force`	Deletes the replication set without prompting the user to confirm the deletion.	Without this flag, the command prompts the user to confirm the deletion.

List

List all replication sets.

evoke replication-set list [command options]

Options

Flag	Description	Default
`-o` , `--output`	Specifies the output format of the list as either text or JSON format.	Text, which returns human-readable YAML output.

Restore

Restore a server from backup. Restores a server from a previously-created backup. Unless otherwise noted, backup and restore can be safely performed across releases of Conjur.

Before issuing the restore command, the backup file should be unpacked using evoke unpack backup.

evoke restore [command options]

Options

Flag	Description	Default
`--accept-eula`	Accept the CyberArk EULA.	Interactively prompt for EULA.
`--internal-account=internal_account`	Sets the internal system account name for the Leader.	system
`-j`, `--json-attributes-file=filename`	Extended JSON attributes.	Extended attributes from a JSON file are not used.
`--preview`	Displays the Conjur policy roles that will be removed during the upgrade process, without actually executing the upgrade. It will list the actions the real migration will take. Always confirm that the roles are no longer used before proceeding without the `--preview` flag. You can use shell commands to put the output in a text file for offline review.	Not applicable

Role

Server role commands.

Promote

Promote a server from standby to Leader.

evoke role promote

Show

Show the current server role (default setting).

evoke role show

Seed

Seed generation.

Follower

Generate a Follower seed.

Generate a seed file, which contains the configuration, cryptographic keys, SSL certificate and private key for a Follower with a given DNS name. The Follower DNS name is generally a virtual IP, (e.g. a load balancer). Additional arguments are used as alternate names when generating the certificate.

When configured, the Follower connects to the Leader using the Leader's primary DNS name. This can be overridden using the configure command's master-ip option.

The output of this command is a tar file printed to stdout. Note that if the stdin of this command has a tty, the tar output may be corrupt.

evoke seed follower [command options]

Options

Flag	Description	Default
`dns-name[, dns-name]*`	The DNS name of the Follower. Domain names can contain a maximum of 63 characters.	None
`--force`	Force removal of existing Follower certificates.	Existing Follower certificates are not forcibly removed.
`--replace-audit-forward`	Remove any existing Follower certificates from mutual TLS for audit forwarding.	Existing Follower certificates from mutual TLS for audit forwarding are not removed.
`--replication-set`	Name of the replication set to use for data segregation per Follower. `evoke seed follower --replication-set <replication-set-name>` The following values are not allowed and will result in an error if used: `ddl_sql` `default` `default_insert_only`	Full If you do not specify a replication set, it defaults to full and all secrets are replicated to the Follower.

If you accidentally remove a trusted certificate, run the evoke seed follower command and redirect its output to /dev/null. While the seed file itself is discarded, a side effect of issuing this command is that a certificate is added to the list of trusted Follower certificates for that node.

Standby

Generate a standby Leader seed.

Generate a seed file that contains configuration and cryptographic keys for a standby Leader. The standby inherits its hostname, certificate, and private key from the Leader.

When configured, the standby connects to the Leader using the its primary DNS name. This can be overridden using the configure command's master-address option.

The output of this command is a tar file printed to stdout.

If the stdin of this command has a tty, the tar output may be corrupt.

evoke seed standby <standby host name> <master-hostname (assuming different from host)>

Unpack

Archive unpacking.

Backup

Unpack a backup file.

If the key is specified as-, then it is read from stdin. The evoke restore command can subsequently be performed without any required options.

evoke unpack backup [command options] backup-data-file

Options

Flag

Description

Default

-k, --key=arg

Encryption key for the backup.

--key is a required flag. If a value is not specified, you receive the following error message:

error: Key file can't be empty

n/a

Seed

Unpack a seed file.

If the seed file name is specified as -, then it is read from stdin. The evoke configure (standby|follower) command can subsequently be performed without any required options.

evoke unpack seed [command options] seed-file

Options

Flag	Description	Default
`-k, --key=arg`	Private key file (if not included in the seed).	Attempt to use key from the seed file.

Variable

Configure environment variables that control the operation of Conjur services.

To maintain backwards compatibility, we continue to support the evoke variable command set. The evoke variable command set can still be used to configure authenticators, but we strongly encourage you to use the conjur.yml) file to preserve your system configuration. For more information, see Manage Conjur configuration

List

List values of some or all environment variables.

evoke variable list [command options] [variable]

Options

Flag	Description	Default
`-q, --quiet`	Don't print informational messages.	Informational messages are printed.

Set

Set the value of a variable.

This command only modifies the current (running) Conjur container. If you are upgrading to a new version of Conjur, previously configured variables DO NOT persist as a new container image is used for the new release. Be sure to reapply your configured variables (e.g. authenticators) after you've finished the upgrade.

Additionally, there is known issue with Leader cluster promotions/failovers. When a Standby is promoted to Leader, configuration set using this command is lost. If you need configuration settings to persist, set environment variables instead when launching the Conjur container with the docker run command. See the Docker Command Summary.

evoke variable set [command options] variable value

Options

Flag	Description	Default
`-q, --quiet`	Don't print informational messages.	Informational messages are printed.
`--[no-]restart`	Restart services after processing.	Services are restarted.

Unset

Unset the value of a variable.

evoke variable unset [command options] variable

Options

Flag	Description	Default
`-q, --quiet`	Don't print informational messages.	Informational messages are printed.
`--[no-]restart`	Restart services after processing.	Services are restarted.

Wait

Wait for Conjur to be ready for requests.

evoke wait [command options]

Options

Flag	Description	Default
`-i, --[no-]ignore-cluster-status`	Ignore Conjur cluster status in determining health.	Do not ignore cluster status.
`-t, --timeout=timeout`	The number of seconds to wait before timeout.	90 seconds.