Using the Infinispan Command Line Interface

The Infinispan CLI exposes different resources to:

Prevent data loss and ensure consistency of your cluster by properly shutting down and restarting nodes.

Infinispan recommends using the shutdown cluster command to stop all nodes in a cluster while saving cluster state and persisting all data in the cache. You can use the shutdown cluster command also for clusters with a single node.

When you bring Infinispan clusters back online, all nodes and caches in the cluster will be unavailable until all nodes rejoin. To prevent inconsistencies or data loss, Infinispan restricts access to the data stored in the cluster and modifications of the cluster state until the cluster is fully operational again. Additionally, Infinispan disables cluster rebalancing and prevents local cache stores purging on startup.

During the cluster recovery process, the coordinator node logs messages for each new node joining, indicating which nodes are available and which are still missing. Other nodes in the Infinispan cluster have the view from the time they join. You can monitor availability of caches using the Infinispan Console or REST API.

However, in cases where waiting for all nodes is not necessary nor desired, it is possible to set a cache available with the current topology. This approach is possible through the CLI, see below, or the REST API.

After using the shutdown server command to bring nodes down, the first node to come back online will be available immediately without waiting for other members. The remaining nodes join the cluster immediately, triggering state transfer but loading the local persistence first, which might lead to stale entries. Local cache stores configured to purge on startup will be emptied when the server starts. Local cache stores marked as purge=false will be available after a server restarts but might contain stale entries.

If you shutdown clustered nodes with the shutdown server command, you must restart each server in reverse order to avoid potential issues related to data loss and stale entries in the cache.
For example, if you shutdown server1 and then shutdown server2, you should first start server2 and then start server1. However, restarting clustered nodes in reverse order does not completely prevent data loss and stale entries.

You can create declarative cache configuration in XML, JSON, and YAML format.

All declarative caches must conform to the Infinispan schema. Configuration in JSON format must follow the structure of an XML configuration, elements correspond to objects and attributes correspond to fields.

add - increments and decrements counters with arbitrary values.

add ['OPTIONS'] ['COUNTER_NAME']

add --delta=10 cnt_a
Increments the value of cnt_a by 10.

add --delta=-5 cnt_a
Decrements the value of cnt_a by 5.

cas(1), reset(1)

alias - creates or displays aliases.

alias ['ALIAS-NAME'='COMMAND']

alias q=quit
Creates q as an alias for the quit command.

alias
Lists all defined aliases.

config(1), unalias(1)

alter - modifies the configuration of caches on ${infinispan.brand.name} Server.

alter cache ['OPTIONS'] CACHE_NAME

You can modify a cache with the alter command only if the changes are compatible with the existing configuration.

For example you cannot use a replicated cache configuration to modify a distributed cache. Likewise if you create a cache configuration with a specific attribute, you cannot modify the configuration to use a different attribute instead. For example, attempting to modify cache configuration by specifying a value for the max-count attribute results in invalid configuration if the max-size is already set.

alter cache mycache --file=/path/to/mycache.json
Modifies the configuration of a cache named mycache with the mycache.json file.

alter cache mycache --attribute=clustering.remote-timeout --value=5000
Modifies the configuration of a cache named mycache so that the clustering.remote-timeout attribute has a value of '5000'.

create(1), drop(1)

availability - manage availability of clustered caches in network partitions.

availability ['OPTIONS'] ['CACHE_NAME']

AVAILABLE makes caches available to all nodes in a network partition. DEGRADED_MODE prevents read and write operations on caches when network partitions occur.

availability cache1
Gets the current availability of the cache 'cache1'.

availability --mode=AVAILABLE cache1
Sets the availability of the cache 'cache1' to AVAILABLE.

backup - manage container backup creation and restoration.

backup create ['OPTIONS']

backup delete ['OPTIONS'] BACKUP_NAME

backup get ['OPTIONS'] BACKUP_NAME

backup ls

backup restore ['OPTIONS'] BACKUP_PATH

backup create -n example-backup
Initiates a backup of all container content with name example-backup.

backup create -d /some/server/dir
Initiates a backup of all container content and stores it on the server at path /some/server/dir.

backup create --caches=* --templates=*
Initiates a backup that contains only cache and cache configuration resources.

backup create --proto-schemas=schema1,schema2
Initiates a backup that contains the named schema resources only.

backup ls
Lists all backups available on the server.

backup get example-backup
Downloads the example-backup archive from the server. If the backup operation is in progress, the command waits for it to complete.

backup restore /some/path/on/the/server
Restores all content from a backup archive on the server.

backup restore -u /some/local/path
Restores all content from a local backup archive that is uploaded to the server.

backup restore /some/path/on/the/server --caches=*
Restores only cache content from a backup archive on the server.

backup restore /some/path/on/the/server --proto-schemas=schema1,schema2
Restores only the named schema resources from a backup archive on the server.

backup delete example-backup
Deletes the example-backup archive from the server.

drop(1)

benchmark - runs a performance benchmark against a cache.

You can run performance benchmarks for the following HTTP and Hot Rod protocols: http, https, hotrod, and hotrods. You specify the protocol for the benchmark with a URI. If you do not specify a protocol, the benchmark uses the URI of the current CLI connection.

Benchmarks for Hot Rod URIs connect to the entire cluster. For HTTP URIs, benchmarks connect to a single node only.

Benchmarks test performance against an existing cache. Before you run a benchmark, you should create a cache with the capabilities you want to measure. For example, if you want to evaluate the performance of cross-site replication, you should create a cache that has backup locations. If you want to test the performance of persistence, create a cache that uses an appropriate cache store.

benchmark ['OPTIONS'] [uri]

benchmark hotrod://localhost:11222
Performs a benchmark test with the Hot Rod protocol.

benchmark --value-size=10000 --cache=largecache hotrod://localhost:11222
Performs a benchmark test with the Hot Rod protocol against the largecache cache using test values that are 10000 bytes in size.

benchmark --mode=All --threads=20 https://user:password@server:11222
Performs a benchmark test with the HTTPS protocol using 20 threads and includes all modes in the report.

cache - selects the default cache for subsequent commands.

cache ['CACHE_NAME']

cache mycache
Selects mycache and is the same as navigating the resource tree using cd caches/mycache.

cd(1), clear(1), container(1), get(1), put(1), remove(1)

cas - performs 'compare-and-swap' operations on strong counters.

cas ['OPTIONS'] ['COUNTER_NAME']

cas --expect=10 --value=20 cnt_a
Sets the value of cnt_a to 20 only if the current value is 10

add(1), cas(1), reset(1)

cd - navigates the server resource tree.

PATH can be absolute or relative to the current resource. ../ specifies parent resources.

cd ['PATH']

cd caches
Changes to the caches path in the resource tree.

cache(1), ls(1), container(1)

clearcache - removes all entries from a cache.

clearcache ['CACHE_NAME']

clearcache mycache
Removes all entries from mycache.

cache(1), drop(1), remove(1)

config - manages CLI configuration properties.

config

config set 'name' 'value'

config get 'name'

config convert --outputFormat=[xml|json|yaml] [-o outputFile] [inputFile]

Manage (list, set, get) CLI configuration properties and provide configuration conversion between the different formats (XML, JSON, YAML)

These options apply to all commands:

The following options apply to the convert command:

config set autoconnect-url http://192.0.2.0:11222
Connects to a server at a custom IP address when you start the CLI.

config get autoconnect-url
Returns the value for the autoconnect-url configuration property.

config set autoexec /path/to/mybatchfile
Runs a batch file named "mybatchfile" when you start the CLI.

config set trustall true
Trusts all server certificates.

config set truststore /home/user/my-trust-store.jks
Specifies the path of a keystore named "my-trust-store.jks".

config set truststore-password secret
Sets the keystore password, if required.

config convert -f yaml -o infinispan.yaml infinispan.xml
Converts the infinispan.xml file to YAML and writes the output to the infinispan.yaml file.

config convert -f json
Converts the configuration from standard input to JSON, and writes the output to standard output.

alias(1), unalias(1)

connect - connects to running ${infinispan.brand.name} servers.

Defaults to http://localhost:11222 and prompts for credentials if authentication is required.

connect ['OPTIONS'] ['SERVER_LOCATION']

connect 127.0.0.1:11322 -u test -p changeme
Connects to a locally running server using a port offset of 100 and example credentials.

disconnect(1)

container - selects the container for running subsequent commands.

container ['CONTAINER_NAME']

container default
Selects the default container and is the same as navigating the resource tree using cd containers/default.

cd(1), clear(1), container(1), get(1), put(1), remove(1)

counter - selects the default counter for subsequent commands.

counter ['COUNTER_NAME']

counter cnt_a
Selects cnt_a and is the same as navigating the resource tree using cd counters/cnt_a.

add(1), cas(1)

create - creates caches and counters on ${infinispan.brand.name} servers.

create cache ['OPTIONS'] CACHE_NAME

create counter ['OPTIONS'] COUNTER_NAME

create cache --template=org.infinispan.DIST_SYNC mycache
Creates a cache named mycache from the DIST_SYNC template.

create counter --initial-value=3 --storage=PERSISTENT --type=strong cnt_a
Creates a strong counter named cnt_a.

drop(1)

credentials - manages keystores that contain ${infinispan.brand.name} Server credentials

credentials ls

credentials add 'alias'

credentials remove 'alias'

credentials mask -i iterations -s salt secret

List, create, and remove credentials inside a keystore and mask keystore passwords. By default, commands manage the credentials.pfx keystore in the server configuration directory.

Add a credential

Remove a credential

credentials add dbpassword -c changeme -p "secret1234!"
Creates a new default credential keystore, if does not already exist, and adds an alias of "dbpassword" for a password of "changeme". This command also sets "secret1234!" as the password for the credential keystore, which must match the password in the server configuration: <clear-text-credential clear-text="secret1234!"/>

credentials ls -p "secret1234!"
Lists all aliases in the default credential keystore.

credentials add ldappassword -t JCEKS -p "secret1234!"
Creates a credential keystore in JCEKS format and adds an alias "ldappassword". This command prompts you to specify the password that corresponds to the alias.

credentials mask "secret1234!" -i 100 -s pepper99 Creates a masked representation of the credential "secret1234!" using 100 iterations using the string pepper99 as salt.

describe - displays information about resources.

describe ['PATH']

describe //containers/default
Displays information about the default container.

describe //containers/default/caches/mycache
Displays information about the mycache cache.

describe //containers/default/caches/mycache/k1
Displays information about the k1 key.

describe //containers/default/counters/cnt1
Displays information about the cnt1 counter.

cd(1), ls(1)

disconnect - ends CLI sessions with ${infinispan.brand.name} servers.

disconnect

disconnect
Ends the current CLI session.

connect(1)

drop - deletes caches and counters.

drop cache CACHE_NAME

drop counter COUNTER_NAME

drop cache mycache
Deletes the mycache cache.

drop counter cnt_a
Deletes the cnt_a counter.

create(1), clearcache(1)

encoding - displays and sets the encoding for cache entries.

Sets a default encoding for put and get operations on a cache. If no argument is specified, the encoding command displays the current encoding.

Valid encodings use standard MIME type (IANA media types) naming conventions, such as the following:

encoding ['ENCODING']

encoding application/json
Configures the currently selected cache to encode entries as application/json.

get(1), put(1)

get - retrieves entries from a cache.

get ['OPTIONS'] KEY

get hello -c mycache
Retrieves the value of the key named hello from mycache.

query(1), put(1)

help - prints manual pages for commands.

help ['COMMAND']

help get
Prints the manual page for the get command.

version(1)

index - manages cache indexes.

index reindex 'cache-name'

index clear 'cache-name'

index update-schema 'cache-name'

index stats 'cache-name'

index clear-stats 'cache-name'

index reindex mycache
Reindexes a cache.

index clear mycache
Clears a cache index.

index update-schema mycache
Updates the index schema for a cache.

index stats mycache
Shows indexing and search statistics for a cache.

index clear-stats mycache
Clears indexing and search statistics for a cache.

query(1)

install - download and install artifacts for ${infinispan.brand.name} Server.

Download and install artifacts to the server/lib directory. You can specify the download location for artifacts as Maven artifact coordinates, a URL, or a local file path.

When downloading Maven artifacts, an optional Maven settings.xml file determines the location of the remote and local repositories as well as credentials and proxy configuration.

If you download artifacts as zip, tar.gz, or tgz archives, the content is extracted.

install 'artifact-1[[|algorithm]|checksum]' ['artifact-2[[|algorithm]|checksum]'…​]

Artifact names can be any of the following:

You can validate the checksum of an artifact after download. The algorithm defaults to SHA-256 but it can also be MD-5, SHA-1, SHA-256, SHA-384, or `SHA-512'.

install -o org.postgresql:postgresql:42.3.1
Installs the PostgreSQL JDBC driver JAR and overwrites if it already exists.

install https://example.org/artifact.zip
Downloads the artifact.zip and extracts the contents.

install https://example.org/artifact.zip|52d73f9b3611610ebbb4dca7c2ac1171218eb09891c1faba10f5f54c1d2acc13
Downloads the artifact.zip, verifies its SHA-256 checksum, and extracts the contents.

install https://example.org/artifact.zip|MD5|2b48d1871ee26f969d8481db94e103c2
Downloads the artifact.zip, verifies its MD-5 checksum, and extracts the contents.

logging - inspects and manipulates the ${infinispan.brand.name} server runtime logging configuration.

logging list-loggers

logging list-appenders

logging set ['OPTIONS'] [LOGGER_NAME]

logging remove LOGGER_NAME

logging list-loggers
Lists all available loggers

logging set --level=DEBUG --appenders=FILE org.infinispan
Sets the log level for the org.infinispan logger to DEBUG and configures it to use the FILE appender.

ls - lists resources for the current path or a given path.

ls ['PATH']

ls caches
Lists the available caches.

ls ../
Lists parent resources.

ls -l --pretty-print=CSV /containers/default/caches/mycache > mycache.csv
Lists the content of a cache, including keys, values and metadata and redirects the contents to a file.

cd(1)

migrate - migrates data from one version of ${infinispan.brand.name} to another.

migrate cluster connect

migrate cluster synchronize

migrate cluster disconnect

migrate cluster source-connection

migrate store

Use the migrate command to migrate data from one version of ${infinispan.brand.name} to another.

Migrate clusters

Migrate stores

These options apply to all commands:

CLUSTER CONNECT OPTIONS

*-P

patch - manages server patches.

List, describe, install, rollback, and create server patches.

Patches are zip archive files that contain artifacts to upgrade servers and resolve issues or add new features. Patches can apply target versions to multiple server installations with different versions.

patch ls

patch install 'patch-file'

patch describe 'patch-file'

patch rollback

patch create 'patch-file' 'target-server' 'source-server-1' ['source-server-2'…​]

patch ls
Lists the patches currently installed on a server in order of installation.

patch install mypatch.zip
Installs "mypatch.zip" on a server in the current directory.

patch install mypatch.zip --server=/path/to/server/home
Installs "mypatch.zip" on a server in a different directory.

patch describe mypatch.zip
Displays the target version and list of source versions for "mypatch.zip".

patch create mypatch.zip 'target-server' 'source-server-1' ['source-server-2'…​]
Creates a patch file named "mypatch.zip" that uses the version of the target server and applies to the source server versions.

patch rollback
Rolls back the last patch that was applied to a server and restores the previous version.

put - adds or updates cache entries.

Creates entries for new keys. Replaces values for existing keys.

put ['OPTIONS'] KEY [VALUE]

put -c mycache hello world
Adds the hello key with a value of world to the mycache cache.

put -c mycache -f myfile -i 500 hola
Adds the hola key with the value from the contents of myfile. Also sets a maximum idle of 500 seconds.

get(1), remove(1)

query - performs Ickle queries to match entries in remote caches.

query ['OPTIONS'] QUERY_STRING

query "from org.infinispan.example.Person p where p.gender = 'MALE'"
Queries values in a remote cache to find entries from a Protobuf Person entity where the gender datatype is MALE.

index(1) schema(1)

quit - exits the command line interface.

quit

exit and bye are command aliases.

quit
Ends the CLI session.

exit
Ends the CLI session.

bye
Ends the CLI session.

disconnect(1), shutdown(1)

rebalance - manages automatic rebalancing for caches

rebalance enable ['PATH']

rebalance disable ['PATH']

rebalance enable
Enables automatic rebalancing in the current context. Running this command in the root context enables rebalancing for all caches.

rebalance enable caches/mycache
Enables automatic rebalancing for the cache named mycache.

rebalance disable
Disables automatic rebalancing in the current context. Running this command in the root context disables rebalancing for all caches.

rebalance disable caches/mycache
Disables automatic rebalancing for the cache named mycache.

remove - deletes entries from a cache.

remove KEY ['OPTIONS']

remove --cache=mycache hola
Deletes the hola entry from the mycache cache.

cache(1), drop(1), clearcache(1)

reset - restores the initial values of counters.

reset ['COUNTER_NAME']

reset cnt_a
Resets the cnt_a counter.

add(1), cas(1), drop(1)

schema - manipulates Protobuf schemas.

schema ls

schema upload --file=/path/to/schema.proto schema.proto

schema remove schema.proto

schema get schema.proto

Manage schemas with the ls, upload, get, remove subcommands.

schema upload --file=person.proto person.proto
Registers a person.proto Protobuf schema.

query(1)

server - server configuration and state management.

The server command describes and manages server endpoint connectors and datasources and retrieves aggregated diagnostic reports about both the server and host.

Reports provide details about CPU, memory, open files, network sockets and routing, threads, in addition to configuration and log files.

server report

server heap-dump [--live]

server connections ls [--global]

server connector ls

server connector describe 'connector-name'

server connector start 'connector-name'

server connector stop 'connector-name'

server connector ipfilter ls 'connector-name'

server connector ipfilter set 'connector-name' --rules='[ACCEPT|REJECT]/cidr',…​

server connector ipfilter clear 'connector-name'

server datasource ls

server datasource test 'datasource-name'

server principals ls

server aclcache flush

server report
Obtains a server report, including information about network, threads, memory, etc.

server heap-dump
Generates a JVM heap dump in the server data directory, returning the name of the generated file.

server connections ls
Lists all active client connections to the server. The --global argument will return connections from all cluster members.

server connector ls
Lists all available connectors on the server.

server connector describe endpoint-default
Shows information about the specified connector, including host, port, local and global connections, IP filtering rules.

server connector stop my-hotrod-connector
Stops a connector dropping all established connections across the cluster. This command will be refused if attempting to stop the connector which is handling the request.

server connector start my-hotrod-connector
Starts a connector so that it can accept connections across the cluster.

server connector ipfilter ls my-hotrod-connector
Lists all IP filtering rules active on a connector across the cluster.

server connector ipfilter set my-hotrod-connector --rules=ACCEPT/192.168.0.0/16,REJECT/10.0.0.0/8 Sets IP filtering rules on a connector across the cluster. Replaces all existing rules. This command will be refused if one of the rejection rules matches the address of the connection on which it is invoked.

server connector ipfilter clear my-hotrod-connector
Removes all IP filtering rules on a connector across the cluster.

server datasource ls
Lists all available datasources on the server.

server datasource test my-datasource
Performs a test connection on the datasource.

server principals ls
Lists principals known by the server.

server aclcache flush
Flushes the security caches cluster-wide.

shutdown - stops server instances and clusters.

shutdown server ['SERVERS']

shutdown cluster

shutdown container

shutdown server
Stops the server to which the CLI is connected.

shutdown server my_server01
Stops the server with hostname my_server01.

shutdown cluster
Stops all nodes in the cluster after storing cluster state and persisting entries if there is a cache store.

shutdown container
Stops the data container without terminating the server process. Stores cluster state and persists entries if there is a cache store. Server instances remain running with active endpoints and clustering. REST calls to container resources will result in a 503 Service Unavailable response. The shutdown container command is intended for environments, such as Kubernetes, that automate resource lifecycle management. For self-managed environments you should use the shutdown server or shutdown cluster commands to stop servers.

connect(1), disconnect(1), quit(1)

site - manages backup locations and performs cross-site replication operations.

site status ['OPTIONS']

site bring-online ['OPTIONS']

site take-offline ['OPTIONS']

site push-site-state ['OPTIONS']

site cancel-push-state ['OPTIONS']

site cancel-receive-state ['OPTIONS']

site push-site-status ['OPTIONS']

site state-transfer-mode get|set ['OPTIONS']

site name

site view

site is-relay-node

site relay-nodes

site status --cache=mycache
Returns the status of all backup locations for mycache.

site status --all-caches
Returns the status of each backup location for all caches with backups.

site status --cache=mycache --site=NYC
Returns the status of NYC for mycache.

site bring-online --cache=mycache --site=NYC
Brings the site NYC online for mycache.

site take-offline --cache=mycache --site=NYC
Takes the site NYC offline for mycache.

site push-site-state --cache=mycache --site=NYC
Backs up caches to remote backup locations.

site push-site-status --cache=mycache
Displays the status of the operation to backup mycache.

site cancel-push-state --cache=mycache --site=NYC
Cancels the operation to backup mycache to NYC.

site cancel-receive-state --cache=mycache --site=NYC
Cancels the operation to receive state from NYC.

site clear-push-state-status --cache=myCache
Clears the status of the push state operation for mycache.

site state-transfer-mode get --cache=myCache --site=NYC
Retrieves the state transfer mode for mycache to NYC.

site state-transfer-mode set --cache=myCache --site=NYC --mode=AUTO
Configures automatic state transfer for mycache to NYC.

site name
Returns the name of the local site. If cross-site replication is not configured, the name of the local site is always "local".

site view
Returns a list of names for all sites or an empty list ("[]") if cross-site replication is not configured.

site is-relay-node
Returns true if the node handles RELAY messages between clusters.

site relay-nodes
Returns a list of relay nodes by their logical names.

stats - displays statistics about resources.

stats ['PATH']

stats //containers/default
Displays statistics about the default container.

stats //containers/default/caches/mycache
Displays statistics about the mycache cache.

cd(1), ls(1), describe(1)

task - executes and uploads server-side tasks and scripts

task upload --file='script' 'TASK_NAME'

task exec ['TASK_NAME']

task upload --file=hello.js hello
Uploads a script from a hello.js file and names it hello.

task exec @@cache@names
Runs a task that returns available cache names.

task exec hello -Pgreetee=world
Runs a script named hello and specifies the greetee parameter with a value of world.

ls(1)

troubleshoot - troubleshooting commands to identify issues in single servers or cluster-wide.

troubleshoot log ['OPTIONS'] ACCESS_LOG_LIST

troubleshoot log access.log access.log.1
Generates statistics grouped by operations from the local files access.log and access.log.1.

troubleshoot log --by-client access.log access.log.1
Generates statistics grouped by clients from the local files access.log and access.log.1.

troubleshoot log -t 10 access.log access.log.1
Displays the 10 operations that took longer to complete from the files access.log and access.log.1.

troubleshoot log -o PUT --start '04/Sep/2024:13:18:14' --end '04/Sep/2024:13:18:15' access.log access.log.1
Generates statistics grouped by operations from the local files access.log and access.log.1. Filters for only PUT operations that happen during the second between the given start and end dates. Note the dates must be quoted.

troubleshoot log -x GET,ERROR --start '04/Sep/2024:13:18:14' --by-client access.log access.log.1
Generates statistics grouped by clients from the local files access.log and access.log.1. Exclude GET and ERROR operations, and only accept operations at or after the given. Note the date must be quoted.

unalias - deletes aliases.

unalias 'ALIAS-NAME'

unalias q
Deletes the q alias.

config(1), alias(1)

user - manages ${infinispan.brand.name} users in property security realms.

user ls

user create 'username'

user describe 'username'

user remove 'username'

user password 'username'

user groups 'username'

user encrypt-all

user roles ls 'principal'

user roles grant --roles='role1'[,'role2'…​] 'principal'

user roles deny --roles='role1'[,'role2'…​] 'principal'

user roles create --description='custom description' --permissions='perm1'[,'perm2'…​] 'role'

user roles update --permissions='perm1'[,'perm2'…​] --description='updated description' 'role'

user roles remove 'role'

user roles describe 'role'

Manage users in property realms with the ls, create, describe, remove, password, groups and encrypt-all subcommands. List and modify principal to role mappings with the roles subcommand when using the cluster role mapper for authorization.

These options apply to all commands:

version - displays the server version and CLI version.

version

version
Returns the version for the server and the CLI.

help(1)