Open topic with navigation

# FTL Administration Utility

Administrators use the FTL administration utility, tibftladmin, to:

- Stop an FTL server process

- Update or dump the realm configuration

- Backup and restore the realm configuration

- Backup and restore persistence data (disk persistence only)

- Compact the realm configuration on disk

- Compact persistence data on disk (online or offline)

Most command line parameters and options have both a short and a long form. The command line parser accepts either form.

## Help

Parameter | Arguments | Description
--- | --- | ---
--help -h |  | Display a help message describing the command line parameters and options.

## Connecting to the FTL Server

Parameter | Arguments | Description
--- | --- | ---
--ftlserver -ftls | <url1>|<url2>|<url3> | Required. Administer the FTL server at this location. You can provide more that one URLs.URLs are pipe seperated, each URL is of the form
    http://<host1>:<port1>
    https://<host1>:<port1>
    http://<host2>:<port2>
    https://<host2>:<port2>
    http://<host3>:<port3>
    https://<host3>:<port3>
--user -u | user_name | Credentials. Required when the FTL server enables user authentication.
--password -pw | password | Credentials. Required when the FTL server enables user authentication. To see the ways to specify a password and to hide the password from casual observers, see Password Security.
--tls.trust.file -tf | <path> | Optional. (Required for TLS communication with a secure FTL server.) The administration utility trusts an FTL server based on this trust file. Supply the file path of a local copy of the FTL server trust file. When both are present, this parameter overrides the parameter: --tls.trust.everyone.
--tls.trust.everyone -te |  | Optional. The administration utility trusts any FTL server without verifying trust in the server's certificate. Warning: Do not use this parameter except for convenience in development and testing. It is not secure.
--oauth2.token | <string> | When the FTL server is setup with oAuth 2.0 authentication provider, then the administrative tool must use the --oauth2.token parameter to specify an oauth2 access token.
--tls.client.cert | <path> | Specify a TLS client certificate for mTLS authentication. The given file must be in PEM format. --tls.client.private.key must be specified as well. If the private key is encrypted, --tls.client.private.key.password must be specified.
--tls.client.private.key | <path> | Specify the private key corresponding to the TLS client certificate. The given file must be in PEM format. Use --tls.client.private.key.password to specify the decrypt passphrase, if needed.
--tls.client.private.key.password | <password> | Decrypt passphrase for the TLS client certificate's private key. It can be specified in one of four ways: 'file:<filename>' The password is in a file specified by filename. The first line of text in the file is used as the password, with leading and trailing whitespace trimmed. 'env:<variable>' The named environment variable is read, and its contents used as the password. 'pass:<password>' The password is specified directly by the parameter. '<password>' The password is specified directly by the parameter. Do not use passwords that begin with any of these reserved prefixes. To hide the password from casual observers use file or env.

## Specifying Files on Disk

Parameter | Arguments | Description
--- | --- | ---
`--datadir` `-d` | <path> | Operates on one of the following: The realm configuration data belonging to the named FTL server The persistence data belonging to the named persistence service Use in conjunction with the `--name` parameter (but not with the `--ftlserver` parameter).
`--name` `-n` | <string> | Operates on one of the following: The realm configuration data belonging to the named FTL server The persistence data belonging to the named persistence service Use in conjunction with the`--datadir` parameter (but not with the `--ftlserver` parameter).

##

## Commands

Commands are mutually exclusive. You may use only one at a time.

Most commands affect an FTL server process that is already running. Specify that FTL server using the --ftlserver parameter.

The following options denote commands that affect a running FTL server process.

`--dumprealm`, `--updaterealm`, `--testupdate`,

`--backup_realm`, `--compact_realm`,

`--backup_persist`, `--compact_online`,

`--status`, `--server_status`, `--cluster_status`,

`--shutdown`, `--shutdown_cluster`, `--available`

Some commands operate on the realm configuration data of an FTL server or the persistence data of a persistence service. Specify the data directory using the `--datadir` parameter. Specify the name of the FTL server or persistence service using the `--name` parameter.

The following options denote commands that operate on the realm configuration data of an FTL server or the persistence data of a persistence service.

`--restore_realm`, `--restore_persist`, `--compact_offline`

Supply commands only on the command line. It is illegal to supply commands in a configuration file.

Parameter | Arguments | Description
--- | --- | ---
--dumprealm -dr | <path> | Write the realm definition to a JSON file at <path>. Modifiers: --debug
--updaterealm -ur | <path> | Update the realm definition from the JSON file at <path>. If a realm definition already exists, the utility replaces the old realm definition with the new definition. This command is available only for a primary server. After updating one primary FTL server, it automatically propagates the new realm definition to all other affiliated servers. Modifiers: --force
--testupdate -tu | <path> | Test deployment using the realm definition in the file at <path>. The realm definition file is in JSON format. For information about the test, seeThe Deploy Transaction
`--backup_realm` |  | Backup the FTL realm configuration. This command creates a backup of the current FTL realm configuration and associated state. A collection of files is written to the backups subdirectory of each FTL server's data directory. The file names incorporate a timestamp. To restore the realm configuration data for a particular FTL server from backup, see`--restore_realm`.
`--backup_persist` |  | Backup the persistence data for the given persistence cluster. The persistence cluster must have disk persistence enabled. The `--cluster <string>` modifier is required. This command creates a backup of all persistence data, including message data and acknowledgments, for the given persistence cluster. The backup files are written to the backups directory of each persistence service in the cluster. The file names incorporate a timestamp. By default, the backup directory for a persistence service is the same as the service's data directory. A different backup directory may be specified setting the `savedir` parameter for the persistence service in the FTL server YAML configuration file. To restore the persistence data for a particular persistence service from backup, see `--restore_backup`. Required modifier: `--cluster <string>`
`--compact_online` |  | Compact the persistence data for the given persistence cluster. The persistence cluster must have disk persistence enabled. The`--cluster <string>` modifier is required. This command causes each persistence service in the given cluster to compact the service's disk persistence files. Active publishers and consumers are not interrupted, though some performance degradation is possible until the compaction completes. See `--compact_offline` for compaction while the persistence service is not running and if online compaction is unwanted or impractical. Modifier: `--cluster <string>`
--status -st |  | Get the status of the FTL server and its clients. Send output to stdout.
--server_status |  | Get the status of the FTL server, but omit the status of its clients. Send the status output to stdout.
--cluster_status |  | Get the status of the FTL server cluster, but omit the status of clients. Send the status output to stdout.
--shutdown -x |  | Stop the FTL server process and all the services it provides. This command is asynchronous, that is, the utility does not wait for confirmation that the server has stopped). To verify that the server has actually stopped, use the --status command. Modifier: `--savestate` When present, the FTL Server saves the state to the disk before exiting. Note: This option is not needed if disk persistence is enabled.
--shutdown_cluster -xc |  | Stop all FTL server processes in the cluster and all the services they provide. This command is asynchronous, that is, the utility does not wait for confirmation that the servers have stopped). To verify that the servers have actually stopped, use the --status command. Modifier: `--savestate` When present, the FTLServer saves the state to the disk before exiting. Note: This option is not needed if disk persistence is enabled.
--available `-a` |  | Check to see if the FTL server is available and all services are running. Returns `200 OK` or `503 Unavailable`.
`--restore_realm` |  | Restore the realm configuration data and associated state of an FTL server (given by `--name`) from backup. The `--backupdir <path>` modifier is required. This command must be executed when the FTL server is not running. This command selects the latest available realm configuration data (as determined by the timestamp in the file names) and copies it to the data directory (given by `--datadir`). There must not be any data files related to the given FTL server in the data directory. Required modifier: `--backupdir <path>`
`--restore_persist` |  | Restore the persistence data of a persistence service (given by `--name`) from backup. The `--backupdir <path>` modifier is required. This command must be executed when the persistence service is not running. This command selects the latest available persistence data (as determined by the timestamp in the file name) and copies it to the data directory (given by `--datadir`). There must not be any data files related to the given persistence service in the data directory. Required modifier: `--backupdir <path>`
`--compact_offline` |  | Compact the disk persistence files of a persistence service (given by `--name)` in its data directory (given by `--datadir`). This command must be executed when the persistence service is not running. Offline compaction may be used when online compaction is unwanted or impractical. (See `--compact_online` for compaction while the persistence service is running.)
`--compact_realm` |  | Compact the FTL realm configuration. This command compacts the database containing the FTL realm configuration. FTL clients are not interrupted.
--hash |  | Accept a password on stdin, and send the hash output to stdout.
--hash_all | <filename or stdin> | Accept a filename for a file (in TIBCO plain text user file format), and send the hash output (all passwords) to stdout. For argument <stdin>, accept input from standard input instead of a file.
--hash_out | filename | Use this parameter with the `--hash_all` parameter. Send the output of hash_all to a filename.
--mask |  | Use this parameter alone to perform password mask encoding explicitly. Mask strings begin with `$mask$`. For example:
    $ tibftladmin --mask
    ************************************************************
    TIBCO FTL FTLAdmin 7.0.1 V2
    Copyright 2009-2024 Cloud Software Group, Inc.
    All Rights Reserved.
--mask_file | inputfilename | Perform password mask encoding on passwords contained in a configuration file and output the file to stdout. Masked passwords begin with $mask$ and the rest of the file is unaltered.
--mask_out | outputfilename | Use with --mask_file to direct output to a specified file. For example:
    $ tibftladmin --mask_file inputfilename --mask_out outputfilename
`--import` | `<path>` | Set a symlink tibemsd `<path to tibems server in bin/modules directory>`. `<path>` must be of the form `<directory>/<filename>`.
`--version` |  | Prints the version of tibftladmin and exits.

## Command Modifiers

Long | Arguments | Description
--- | --- | ---
--force |  | When present along with --updaterealm, break the realm lock, discarding any undeployed changes to the realm definition.
--debug |  | When present along with --dumprealm, dump additional information for debugging. Use only when TIBCO support staff request this information.
--savestate | <true or false> | When present along with `-xc --shutdown_cluster` or `-x --shutdown`, the FTL Server saves the state to the disk before exiting. Note: This option is not needed if disk persistence is enabled.
`--cluster` | <string> | Name a persistence cluster for the -`-backup_persist` or `--compact_online` commands.
`--backupdir` | <path> | Identify the location of backup files for the `--restore_realm` or `--restore_persist` commands.

Did you find this helpful?

Yes No
Great!
Thanks for taking the time to give us some feedback.
Sorry about that

Why wasn't this helpful? (check all that apply)

Could not find what I was looking for
Instructions confusing or unclear
Instructions did not work

Want to tell us more?

Please select at least one option or provide details about the issue!!

Error occurred while submitting feedback.

Error2 occurred while submitting feedback.

TIBCO FTL® - Enterprise Edition

Copyright © 2009-2024. Cloud Software Group, Inc. All Rights Reserved.