LKCLI is a command-line interface for managing SIOS LifeKeeper cluster resources via the LifeKeeper REST API. It allows you to create and manage cluster resources, communication paths, resource dependencies, and API access keys from a shell prompt or automation script.

LKCLI communicates with a LifeKeeper REST API server running on a cluster node. Each command targets a single server (specified via --host). Commands can be run against each node in the cluster as needed.

Table of Contents

Authentication and Profiles

LKCLI supports two authentication methods:

  1. Password-based authentication - Pass --username and --password directly on the command line (or supply the password via the LKCLI_PASSWORD environment variable or interactive shell prompt). The CLI exchanges these credentials for a short-lived JSON web token (JWT) and uses it for the request.
  1. User profiles - Store an API key for a host in a local credentials file using lkcli profile add-key or lkcli profile configure. When a matching stored key is found for the target host and active profile, it is used automatically without needing --username/--password.

Profiles are named sets of stored credentials and configuration settings. The active profile is selected via the --profile flag or the LKCLI_PROFILE environment variable (default: default). Each stored API key grants access to the LifeKeeper REST API only on the server where it was created. Named profiles can store API keys for multiple hosts (e.g., one for each server in the LifeKeeper cluster).

Configuration Files

LKCLI stores its configuration in two YAML files under the .lkcli directory in your home folder:

File Path Purpose
config.yml %USERPROFILE%\.lkcli\config.yml Non-sensitive per-host settings (API port, timeouts). Created automatically on first run with commented-out examples.
credentials.yml %USERPROFILE%\.lkcli\credentials.yml API key credentials (key ID and secret). Restricted to owner-only file permissions.

config.yml structure

config.yml holds non-sensitive per-host settings organized by profile. Each profile can specify settings for one or more hosts. The optional top-level default_profile key overrides the built-in default profile name (default).

# %USERPROFILE%\.lkcli\config.yml

# Optional: override the built-in default profile name
default_profile: default

profiles:
  default:
    hosts:
      server1.corp.example.com:
        api_port: 5000
        timeout_connection: 120
        timeout_read: 600
      server2.corp.example.com:
        api_port: 5000

  production:
    hosts:
      lk-prod-01.corp.example.com:
        api_port: 5010
        timeout_connection: 180
        timeout_read: 720
      lk-prod-02.corp.example.com:
        api_port: 5010
        timeout_connection: 180
        timeout_read: 720

Supported per-host keys in config.yml:

Key Type Description
api_port int TCP port the REST API is listening on
timeout_connection int Connection timeout in seconds (0 = no timeout, default = 60 seconds)
timeout_read int Streaming read timeout in seconds (0 = no timeout, default = 300 seconds)

credentials.yml structure

credentials.yml holds API key credentials organized by profile and host. This file is written automatically by lkcli profile add-key and lkcli profile configure. Its permissions are enforced to be owner-only, and LKCLI will refuse to read it if the permissions are too permissive.

# %USERPROFILE%\.lkcli\credentials.yml

profiles:
  default:
    hosts:
      server1.corp.example.com:
        key_id: lk_a1b2c3d4e5f6a7b8c9d0e1f2
        secret: lks_000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
        username: lkadmin
        role: admin
        managed: true
      server2.corp.example.com:
        key_id: lk_b2c3d4e5f6a7b8c9d0e1f2a3
        secret: lks_202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f
        username: lkadmin
        role: admin
        managed: true

Credential fields:

Field Description
key_id Public key identifier (lk_ + 24 hex characters)
secret Key secret (lks_ + 48 hex characters). Never displayed in LKCLI output.
username LifeKeeper username the key was created for
role Role assigned to the key (guest, operator, or admin)
managed If true, LKCLI will revoke the key on the server when profile remove-key --revoke is run or when profile refresh-key replaces it

Configuration Precedence

When determining the value for a configurable setting, LKCLI applies the following precedence order (highest to lowest):

Connection settings (--api-port, --timeout-connection, --timeout-read)

  1. CLI flag - value passed explicitly on the command line (e.g., --api-port=5001)
  2. config.yml per-host entry - value stored under the active profile and target host
  3. Built-in default - the default value compiled into LKCLI (see Global Flags)

Active profile name

  1. --profile flag - profile name passed explicitly on the command line
  2. LKCLI_PROFILE environment variable - e.g., export LKCLI_PROFILE=production
  3. default_profile key in config.yml - top-level key in the config file
  4. Built-in default - the literal string default

Authentication credentials

  1. --username / --password flags - password-based authentication; the CLI exchanges them for a short-lived JWT
    1. Password resolution order when --username is provided:
      1. --passwordflag
      2. LKCLI_PASSWORD environment variable
      3. Interactive prompt (only when attached to a TTY)
  1. Stored API key - key ID and secret loaded from credentials.yml for the active profile and target host. The host name in the credentials.yml file must match the value of the --host flag (default localhost) exactly in order for credential lookup to succeed.

Global Flags

The following flags are accepted by every LKCLI command:

Flag Type Default Description
--host string localhost Hostname or IP address of the LifeKeeper REST API server
--api-port int 5000 TCP port the REST API server is listening on
--username string Username for password-based authentication
--password string Password for password-based authentication (overrides LKCLI_PASSWORD environment variable)
--profile string default Active profile name; selects which stored API key and persistent configuration settings to use (case-sensitive; overrides LKCLI_PROFILE environment variable)
--debug bool false Enable verbose debug logging to stderr
--timeout-connection int 60 Seconds to wait for the server to return response headers (0 = no timeout; overrides per-host timeout_connection settings in config.yml)
--timeout-read int 300 Seconds to wait for the end of a streaming response after headers are received (0 = no timeout; overrides per-host timeout_read settings in config.yml)

Exit Codes

LKCLI commands use the following exit codes:

Code Name Condition
0 Success Command completed successfully
1 GenericError Flag parsing error, validation error, or response handling error
2 ClientError HTTP 4xx response from the server (e.g., 401 Unauthorized, 404 Not Found)
3 ServerError HTTP 5xx response from the server
4 UnexpectedHTTPStatus HTTP response with a status code not in the success list and not 4xx/5xx
5 ServerConnectionError Network-level error (e.g., connection refused, DNS failure)
6 ServerConnectionTimeout Connection or streaming read timeout elapsed
7 ServerConnectionLost TCP connection dropped mid-request
8 ServerMalformedResponse API response could not be parsed or was malformed

Command Groups

status

Reports a summary of the LifeKeeper LCD (LifeKeeper Configuration Database) configuration, including all registered resources and systems in the cluster.

Required role: guest

lkcli status [flags]

This command has no command-specific flags.

Example:

lkcli status --host=server1

communication-path

Commands for managing LifeKeeper communication paths between cluster nodes.

Aliases: commpath

communication-path create

Create a new communication path between the target server and a remote server in the cluster.

Required role: admin

lkcli communication-path create --remote-sys=<string> --local-ip=<string> --remote-ip=<string> [flags]

Flag Short Type Required Default Description
--remote-sys -r string Yes Hostname of the remote server
--local-ip -l string Yes IP address of the local server endpoint
--remote-ip -e string Yes IP address of the remote server endpoint
--heartbeat-interval -i int No 6 Heartbeat interval in seconds
--max-heartbeat-misses -m int No 5 Maximum heartbeat misses before path is considered down
--priority -p int No Priority of the communication path (lower = higher priority)
--port -o int No TCP port used for the communication path

Example:

lkcli communication-path create \
  --host=server1 \
  --remote-sys=server2 \
  --local-ip=192.168.1.10 \
  --remote-ip=192.168.1.20

communication-path delete

Delete an existing communication path between the target server and a remote server.

Required role: admin

lkcli communication-path delete --remote-sys=<string> --local-ip=<string> --remote-ip=<string> [--priority=<int>] [flags]

Flag Short Type Required Default Description
--remote-sys -r string Yes Hostname of the remote server
--local-ip -l string Yes Local IP address of the communication path
--remote-ip -e string Yes Remote IP address of the communication path
--priority -p int No Priority of the communication path

Example:

lkcli communication-path delete \
  --host=server1 \
  --remote-sys=server2 \
  --local-ip=192.168.1.10 \
  --remote-ip=192.168.1.20

communication-path list

List all communication paths defined on the target server, with optional filters.

Required role: guest

lkcli communication-path list [flags]

Flag Short Type Required Default Valid Values Description
--device -d string No Filter by device (e.g., TCPIP:1500)
--local-ip -l string No Filter by local IP address
--priority -p int No Filter by priority
--remote-sys -r string No Filter by remote system hostname
--remote-ip -e string No Filter by remote IP address
--state -s enum No ALIVE, DEAD, UNKNOWN, ILLSYS Filter by path state
--type -t enum No TLI, TTY, SCSI, ILLNET Filter by protocol type

Examples:

lkcli communication-path list --host=server1
lkcli communication-path list --host=server1 --state=ALIVE
lkcli communication-path list --host=server1 --remote-sys=server2

server

Commands for managing properties and configuration of a LifeKeeper server.

server get-properties

Get all properties and failover policy settings for the local server. Returns the server name, state (ALIVE, DEAD, UNKNOWN, or ILLSYS), and failover policy settings.

Aliases: get-properties, info

Required role: guest

lkcli server get-properties [flags]

This command has no command-specific flags.

Example:

lkcli server get-properties --host=server1

server set-shutdown-strategy

Set the shutdown switchover strategy for the local server. Controls whether resources automatically switch over to a standby server when the local server is gracefully shut down.

Required role: admin

lkcli server set-shutdown-strategy --value=<switchover|do_not_switchover> [flags]

Flag Short Type Required Default Valid Values Description
--value -v enum Yes switchover, do_not_switchover Shutdown switchover strategy

Examples:

lkcli server set-shutdown-strategy --host=server1 --value=switchover
lkcli server set-shutdown-strategy --host=server1 --value=do_not_switchover

resource

Commands for listing, inspecting, and managing the state of LifeKeeper resources. Resource type-specific subcommands (create, extend, get-property, set-property, and resource-specific actions) are accessible via the resource type path (e.g., lkcli resource comm/ip create).

See the Resource Types directory for per-resource-type documentation.

resource list

List all LifeKeeper resources on the specified server, with optional filters.

Required role: guest

lkcli resource list [flags]

Flag Short Type Required Default Description
--application -a string No Filter by application category (e.g., comm, gen, database, filesys)
--id -i string No Filter by LifeKeeper resource identifier
--kit-properties -p array No Retrieve additional resource-specific property values (comma-separated list of property names, or all to retrieve all resource-specific properties)
--resource-type -r string No Filter by resource type (e.g., ip, app, sqlapp, volume)
--state -s string No Filter by resource state (e.g., ISP, OSU, OSF)
--tag -t string No Filter by resource tag name

Examples:

lkcli resource list --host=server1
lkcli resource list --host=server1 --state=ISP
lkcli resource list --host=server1 --resource-type=volume --kit-properties=all
lkcli resource list --host=server1 --application=comm \
  --kit-properties=ip_address,netmask

resource info

Get detailed information about a specific LifeKeeper resource by its tag.

Required role: guest

lkcli resource info --tag=<string> [flags]

Flag Short Type Required Default Description
--tag -t string Yes Resource tag name
--kit-properties -p array No Retrieve additional resource-specific property values (comma-separated list of property names, or all to retrieve all resource-specific properties)

Example:

lkcli resource info --host=server1 --tag=ip-172.31.1.10
lkcli resource info --host=server1 --tag=Vol.D \
  --kit-properties=volume_letter,volume_size

resource remove

Take a LifeKeeper resource out of service.

Required role: operator

lkcli resource remove --tag=<string> [flags]

Flag Short Type Required Default Description
--tag -t string Yes Resource tag name

Example:

lkcli resource remove --host=server1 --tag=ip-172.31.1.10

resource restore

Bring a LifeKeeper resource in-service.

Required role: operator

lkcli resource restore --tag=<string> [flags]

Flag Short Type Required Default Description
--tag -t string Yes Resource tag name

Example:

lkcli resource restore --host=server1 --tag=ip-172.31.1.10

Resource Type Subcommands

Resources are created and managed via resource type paths. The general form is:

lkcli resource <type> <subcommand> [flags]

Available subcommands for resource types:

Subcommand Description Required Role
create Create a new resource on the target server admin
extend Extend an existing resource to a standby server admin
get-property Read the value of a resource property guest
set-property Update the value of an editable resource property admin

Some resource types also expose additional action subcommands (e.g., filesys/volume break). See the documentation for each resource type for details.

Available resource types and their aliases:

Resource Type Aliases Description
comm/ip ip IP Address resource
comm/dns dns DNS resource
comm/ecc ecc, ec2 Amazon EC2 resource
comm/lbhc lbhc Load Balancer Health Check resource
comm/ocivip ocivip OCI Virtual IP resource
comm/route53 route53 Amazon Route 53 DNS resource
comm/volshare volshare File Share List resource
database/listener listener Oracle Listener resource
database/oraapp oraapp Oracle Database resource
database/pdb pdb Oracle Pluggable Database resource
database/pgsqlapp pgsqlapp, pgsql PostgreSQL Database resource
database/sqlapp sqlapp Microsoft SQL Server resource
filesys/volume volume Volume resource
gen/app gen Generic Application resource
gen/hulft hulft HULFT resource
gen/qsp qsp Quick Service Protection resource
appsuite/jp1ajs jp1ajs Hitachi JP1/AJS resource
WEBServer/webapp webserver/webapp, webapp, iis IIS (Internet Information Services) resource

resource-hierarchy

Commands for managing LifeKeeper resource hierarchy branches (a hierarchy is the full tree of a set of root resources and all their dependents).

resource-hierarchy delete

Delete one or more LifeKeeper resource hierarchy branches from the cluster. All resources in each named branch are removed from every live server in the cluster as long as they do not also appear in a different branch of the hierarchy. This is a long-running operation with streaming output.

Required role: admin

lkcli resource-hierarchy delete --roots=<array> [flags]

Flag Short Type Required Default Description
--roots -r array Yes Comma-separated list of root resource tags to delete (e.g., tag1,tag2)

Examples:

lkcli resource-hierarchy delete --host=server1 --roots=ip-172.31.1.10
lkcli resource-hierarchy delete --host=server1 --roots=tag1,tag2

resource-hierarchy reorder-priorities

Reorder the failover priorities of servers in a resource hierarchy. When comparing two servers as potential failover candidates for a resource hierarchy, the server with the lower priority value takes precedence.

Required role: admin

lkcli resource-hierarchy reorder-priorities --tag=<string> --priorities=<object> [flags]

Flag Short Type Required Default Description
--tag -t string Yes Resource tag name
--priorities -p object Yes Server priorities as hostname=priority pairs, comma-separated (e.g., server1=1,server2=10)

Example:

lkcli resource-hierarchy reorder-priorities \
  --host=server1 \
  --tag=ip-172.31.1.10 \
  --priorities=server1=1,server2=10

resource-hierarchy unextend

Unextend the resource hierarchy containing the specified resource from the target server. All resources in the hierarchy must be out of service on the target server before running this command.

Required role: admin

lkcli resource-hierarchy unextend --tag=<string> [flags]

Flag Short Type Required Default Description
--tag -t string Yes Tag of any resource within the hierarchy to unextend

Example:

lkcli resource-hierarchy unextend --host=server2 --tag=ip-172.31.1.10

dependency

Commands for managing parent-child dependency relationships between LifeKeeper resources.

dependency create

Create a parent-child dependency relationship between two resources.

Required role: admin

lkcli dependency create --parent=<string> --child=<string> [flags]

Flag Short Type Required Default Description
--parent -p string Yes Parent resource tag
--child -c string Yes Child resource tag

Example:

lkcli dependency create --host=server1 --parent=app.0 --child=ip-172.31.1.10

dependency delete

Delete an existing parent-child dependency relationship.

Required role: admin

lkcli dependency delete --parent=<string> --child=<string> [flags]

Flag Short Type Required Default Description
--parent -p string Yes Parent resource tag
--child -c string Yes Child resource tag

Example:

lkcli dependency delete --host=server1 --parent=app.0 --child=ip-172.31.1.10

dependency list

List parent-child dependency relationships, with optional filters.

Required role: guest

lkcli dependency list [--parent=<string>] [--child=<string>] [flags]

Flag Short Type Required Default Description
--parent -p string No Filter by parent resource tag
--child -c string No Filter by child resource tag

Example:

lkcli dependency list --host=server1 --parent=app.0

log

Commands for accessing LifeKeeper event log data.

log get-events

Retrieve and display LifeKeeper log events from the target server, optionally limiting the number of events returned.

Required role: guest

lkcli log get-events [--limit=<int>] [flags]

Flag Short Type Required Default Constraints Description
--limit -n int No 10 min: 1, max: 1000 Maximum number of log events to return

Examples:

lkcli log get-events --host=server1
lkcli log get-events --host=server1 --limit=100

access-key

Commands for managing LifeKeeper REST API access keys. Non-admin users may only manage their own keys. Admin users may manage keys for any user.

access-key create

Create a new API access key for the currently authenticated user on the target server. The key’s role cannot exceed the authenticated user’s own role. The secret value is shown only once in the response and cannot be recovered later.

Required role: guest

lkcli access-key create --role=<guest|operator|admin> [flags]

Flag Short Type Required Default Constraints Description
--role enum Yes guest, operator, admin Role to assign to the new key (cannot exceed your own role)
--description string No "API key for <user> (<role>) created at <datetime>" Max 256 characters Human-readable description of the key’s purpose
--expiration-days int No Default value configurable on the server min: 0 Days until key expires; 0 = indefinite (only for guest keys); server configures the default and maximum

Example:

lkcli access-key create \
  --host=server1 \
  --username=lkadmin \
  --password=secret \
  --role=operator \
  --description="Operator key for lkadmin@server1" \
  --expiration-days=90

access-key delete

Revoke a single API access key by its key ID. Non-admin users may only revoke their own keys.

Required role: guest

lkcli access-key delete --key-id=<string> [flags]

Flag Short Type Required Default Constraints Description
--key-id string Yes Format: lk_ + 24 hex characters The key ID to revoke
--reason string No Max 256 characters Optional reason for revocation; Optional reason for revocation to be stored with the revoked key; if available, the reason can be viewed with lkcli access-key info or lkcli access-key list --include-inactive.

Example:

lkcli access-key delete \
  --host=server1 \
  --key-id=lk_a1b2c3d4e5f6a7b8c9d0e1f2 \
  --reason="Key rotation"

access-key delete-all

Revoke all active API access keys for a user. Without --target-user, this command revokes the authenticated user’s own keys. Admin users may specify --target-user to target another user.

Required role: guest (own keys); admin (another user’s keys via --target-user)

lkcli access-key delete-all [flags]

Flag Short Type Required Default Description
--target-user string No Currently authenticated user Username whose keys to revoke (admin only)
--reason string No Optional reason for revocation to be stored with the revoked key; if available, the reason can be viewed with lkcli access-key info or lkcli access-key list --include-inactive.

Example:

lkcli access-key delete-all \
  --host=server1 \
  --username=lkadmin \
  --password=secret \
  --target-user=lkuser \
  --reason="Account deactivated"

access-key info

Get full details of a single API access key by its key ID. Non-admin users may only retrieve their own keys.

Required role: guest

lkcli access-key info --key-id=<string> [flags]

Flag Short Type Required Default Constraints Description
--key-id string Yes Format: lk_ + 24 hex chars The key ID to retrieve

Example:

lkcli access-key info --host=server1 --key-id=lk_a1b2c3d4e5f6a7b8c9d0e1f2

access-key list

List API access keys. Without filter flags, the command returns the authenticated user’s own active keys.

Required role: guest (own keys); admin (--target-user or --all-users)

lkcli access-key list [flags]

Flag Short Type Required Default Description
--target-user string No List keys for this specific user (admin only; mutually exclusive with --all-users)
--all-users bool No false List keys for all users (admin only; mutually exclusive with --target-user)
--include-inactive bool No false Also include recently revoked and recently expired keys

Examples:

lkcli access-key list --host=server1
lkcli access-key list --host=server1 --target-user=lkuser
lkcli access-key list --host=server1 --all-users
lkcli access-key list --host=server1 --all-users --include-inactive

profile

Commands for managing local credential profiles. Profiles store API keys for one or more hosts, eliminating the need to pass --username/--password on every command.

Profile data is stored in local configuration files (%USERPROFILE%/.lkcli/config.yml and %USERPROFILE%/.lkcli/credentials.yml).

profile add-key

Authenticate with basic credentials (username/password), create a new API key on the server, and store it in the active profile’s credentials file. After running this command, subsequent commands targeting the same host will use the stored key automatically.

Required role: guest

lkcli profile add-key [flags]

Flag Short Type Required Default Constraints Description
--username string Yes Username of the account to generate the API access key for
--password string Yes Password for the account to generate the API access key for (overrides LKCLI_PASSWORD environment variable)
--role enum No guest guest, operator, admin Role to assign to the new key (cannot exceed your own role)
--description string No "LKCLI profile key for <user>@<host> created at <datetime>" Max 256 characters Human-readable description of the key’s purpose
--expiration-days int No Default value configurable on the server min: 0 Days until key expires; 0 = indefinite (only for guest keys); server configures the default and maximum

Example:

lkcli profile add-key \
  --host=server1 \
  --username=lkadmin \
  --password=secret \
  --role=admin \
  --description="LKCLI key for server1" \
  --expiration-days=180

profile configure

Store a pre-existing API key into the credentials file under the active profile. Use this when you already have a key ID and secret (e.g., from access-key create) and want to register it locally. If the API key secret is not provided via the --secretflag, then the user will be prompted for it interactively if attached to a TTY. If the --managed flag is provided, LKCLI will assume responsibility for managing the lifecycle of the API key (i.e., lkcli profile remove-key will revoke the key on the server in addition to removing it from the local credentials file).

Required role: N/A (local-only operation)

lkcli profile configure --key-id=<string> [flags]

Flag Short Type Required Default Constraints Description
--key-id string Yes Format: lk_ + 24 hex chars The key ID to store
--secret string Yes Format: lks_ + 48 hex chars The key secret to store; prompted for interactively if not provided
--username string Yes Username associated with the API key (for informational purposes only)
--role enum No guest guest, operator, admin Role to store with the API key (for informational purposes only)
--managed bool No false Whether LKCLI should manage the lifecycle of this API key

Example:

lkcli profile configure \
  --host=server1 \
  --username=lkadmin \
  --key-id=lk_a1b2c3d4e5f6a7b8c9d0e1f2
# (prompts for secret interactively)

profile info

Display the stored configuration and credential metadata for the active profile.

Required role: N/A (local-only operation)

lkcli profile info [--profile=<string>] [flags]

This command has no command-specific flags.

profile list

List all profile names defined in the local configuration and credentials files (%USERPROFILE%\.lkcli\config.yml and %USERPROFILE%\.lkcli\credentials.yml).

Required role: N/A (local-only operation)

lkcli profile list [--profile=<string>] [flags]

This command has no command-specific flags.

profile refresh-key

Using the existing API key, create a new API key on the server and store it in the active profile. If the existing API key is stored with managed: true, LKCLI will automatically revoke the old key. Useful for rotating API keys without losing access.

Required role: guest

lkcli profile refresh-key [flags]

Flag Short Type Required Default Constraints Description
--role enum No guest guest, operator, admin Role to assign to the new key (cannot exceed the stored key’s role)
--description string No "LKCLI profile key for <user>@<host> refreshed at <datetime>" Max 256 characters Human-readable description of the new key’s purpose
--expiration-days int No Default value configurable on the server min: 0 Days until new key expires; 0 = indefinite (only for guest keys); server configures the default and maximum
--reason string No "Replaced by lkcli profile refresh-key" Max 256 characters Optional reason for revocation of the old key (if managed by LKCLI)

Example:

lkcli profile refresh-key --host=server1 \
  --role=admin \
  --description="Administrator key for server1" \
  --expiration-days=180 \
  --reason="Key rotation"

profile remove-key

Remove the stored credential for the target host from the active profile. Optionally revoke the key on the server at the same time.

Required role: N/A for --local-only; guest for --revoke

lkcli profile remove-key [--local-only | --revoke] [flags]

Flag Short Type Required Default Description
--local-only bool No Remove only the local entry; do not contact the server (mutually exclusive with --revoke)
--revoke bool No Revoke the key on the server and remove the local entry (mutually exclusive with --local-only)

Examples:

lkcli profile remove-key --host=server1 --local-only
lkcli profile remove-key --host=server1 --revoke

Feedback

Was this helpful?

Yes No
You indicated this topic was not helpful to you ...
Could you please leave a comment telling us why? Thank you!
Thanks for your feedback.

Post your comment on this topic.

Post Comment