Fortinet black logo

Administration Guide

FortiSOAR Admin CLI

Copy Link
Copy Doc ID b60b554b-4ea9-11ed-9d74-fa163e15d75b:12606
Download PDF

FortiSOAR Admin CLI

An administrator can use FortiSOAR Admin CLI (csadm) to perform various functions such as backing up and restoring data and run various FortiSOAR commands such as starting and stopping services and collecting logs.

Prerequisites

To run csadm you must login as root or have sudo permissions.

FortiSOAR Admin CLI - Usage

Once you type # csadm on the command prompt, the usage and subcommands of the FortiSOAR Admin CLI are displayed as shown in the following image:

FortiSOAR™ Admin CLI command prompt

To perform a particular task in FortiSOAR using csadm, you must type # csadm and then its subcommand and the subcommand’s arguments (if any). For example, to change a hostname use the following command:
# csadm hostname --set [<hostname to be set>]

You can get help for a particular subcommand by running following command:
# csadm <subcommand>
OR
# csadm <subcommand> --help

csadm supports the following subcommands:

Subcommand Description
certs

Generates and deploys your certificates. You can use the following arguments with this subcommand:

  • --deploy: Deploys SSL certificates. For more information, see the Updating the SSL certificates section in the Additional configuration settings for FortiSOAR chapter in the "Deployment Guide."

  • --generate <host name>: Generates and deploys self-signed certificates. You can use the --no-replace-nginx-cert argument with this command, if you do not want to replace your nginx self-signed certificates.

db

Performs operations related to database.
You can use the following arguments with this subcommand:

  • --archival-externalize [ARCHIVAL_DB]: Externalizes your data archival database.

  • --backup [<backup_dir_path>]: Performs a backup of your FortiSOAR system, including backup of both data and configuration files in the directory you have specified.
    From version 6.4.3 onwards, you can optionally use the --exclude-workflow option to exclude all the "Executed Playbook Logs" from the backup. For more information, see the Backing up and Restoring FortiSOAR chapter.

  • --backup-config [<backup_dir_path>]: Performs a backup of only your configuration files in the directory you have specified.

  • --change-passwd: Changes the password of your PostgreSQL database.
    Once you run this command, you will be prompted to enter the password of your choice and confirm the password, which will then update your PostgreSQL database password to the new password.

  • --check-connection: Checks the database connection that is mentioned in the db_external_config.yml file.

  • --restore [<backup_file_path>]: Performs data restore from a locally stored file, whose path you have specified. The default location of the backup file is (/home/csadmin/db_backup/DR_BACKUP_<yyyymmdd_hhmmss>.tgz). For more information, see the Backing up and Restoring FortiSOAR chapter.

  • -encrypt: Generates an encrypted version of the text that you have specified on the prompt. Use this command to generate an encrypted version of the password that you have set for your PostgreSQL database.

  • --externalize: Performs externalization of your FortiSOAR PostgreSQL data. You must provide the path in which you want to save your database backup file. For more information, see the Externalization of your FortiSOAR PostgreSQL database chapter.
    --check-connection: Checks the connection between FortiSOAR and the external PostgreSQL database.

  • --getsize: Displays the size of the primary data and the audit and workflow logs in your database. This enables you to see the current usage and calculate usage over time based on your purging policy.

From version 7.0.0 onwards, you can also backup and restore the data of your external Secure Message Exchange (SME) system, by using the following arguments with the db subcommand:

  • --backup [<backup_dir_path>]: Performs a backup of your external SME system.

  • --restore [<backup_file_path>: Performs data restore for your external SME system from a locally stored file, whose path you have specified. The default location of the backup file is (/home/csadmin/db_backup/DR_BACKUP_<yyyymmdd_hhmmss>.tgz). For more information, see the Backing up and Restoring FortiSOAR chapter.
    Note: All other options of the db option are not applicable to the external SME.

ha Manages your FortiSOAR High Availability cluster. For more information about HA and its commands, see the High Availability support in FortiSOAR chapter.
hostname

Changes the name of the host and Fully Qualified Domain Name (FQDN) based on the parameters you have specified. You can use the following arguments with this subcommand:

  • --set [<hostname>]: If you specify a new hostname, then this changes your current hostname to the new hostname that you have specified, sets up the message broker, regenerates certificates, and restarts FortiSOAR services.
    If you do not specify a hostname, then this sets up the message broker, regenerates certificates using the existing hostname, and restarts FortiSOAR services.
    Note: Before you run this subcommand, you must ensure that the specified hostname is resolvable.

  • --dns-name <DNS_SERVER_IP>: Adds the DNS server entry to the /etc/resolv.conf file.

license

Manages your FortiSOAR license. You can use the following arguments with this subcommand:

  • --get-device-uuid : Retrieves the Device UUID for your FortiSOAR instance.

  • --deploy-enterprise-license <License File Path>: Deploys your FortiSOAR enterprise license. For example, csadm license --deploy-enterprise-license temp/<Serial_No>.lic.

  • --deploy-multi-tenant-license <License File Path>: Deploys your FortiSOAR multitenancy license.

  • --show-details: Displays details of the installed license such as, type of license, Device UUID, expiry date of the license, etc. If you add the [License File Path] parameter to this subcommand, for example --show-details /home/<Serial_No>.lic, then this displays the contents of the license file.

user

Manages your FortiSOAR users. You can use the following options with this subcommand:

  • show-logged-in-users: Displays a list of currently logged in users whose access type is 'Concurrent'.
    The following arguments can be used with this option:
    • --access-type {Named,Concurrent}: Access type, i.e., Named or Concurrent, of the users that you want to include in the list of currently logged in users. For example, if you specify csadm user show-logged-in-users --access-type Named, then the list of 'named' users currently logged into FortiSOAR will be displayed. By default, the access type is set as Concurrent.

    • --limit [1-30]: Last n users who have logged into FortiSOAR. Use this argument to limit the number of users that you want to display in the list of currently logged in users. For example, if you specify csadm user show-logged-in-users --limit 5, then the list will display the last 5 logged in users. By default, the limit is set to 10. You can specify any value between 1 to 30.

  • logout-user --username USERNAME: Forcefully logs out a specific 'Concurrent' user from FortiSOAR; 'Named' users cannot be logged out. You must specify the username argument with this option, i.e., you must include the username of the user you want to log out of FortiSOAR. For example, to log out testuser1, specify csadm user logout-user --username testuser1
mq

FortiSOAR message queue controller (RabbitMQ) functions. You can use the following options with this subcommand:

  • certs: Manages the TLS certificates of the RabbitMQ server.
    You can perform the following actions with this option:

    • generate: Generates the self-signed certificate that will be used for authenticate connections between the secure message exchange (RabbitMQ server) and any client or agent or distributed tenant.
      This generates the signed certificates for the secure message exchange with the CA name as 'FSRDefaultCA'. If you have already deployed your own organization's signed certificate for the secure message exchange, then this subcommand will not overwrite your certs, instead a proper message will be displayed and the subcommand will exit.
      Note: If there are any FSR agents connected to this secure message exchange then you must download and run the agent installer again for the new certificates to be available to the agents.
    • deploy: Deploys the server certificates. You must use the following arguments with this action:
      • --ca-cert MQ_CA_CERT_PATH: Location of the CA certificates. By default, the CA certificate for the FortiSOAR self-signed certificate is present at the following location: /opt/cyops/configs/rabbitmq/ssl/cyopsca/cacert.pem
        Important: The input .pem files must be in the 'Unix' format. You can use dos2unix CLI to convert it to the Unix format.
      • --server-cert MQ_SERVER_CERT_PATH: Location of the server certificates.
      • --server-key MQ_SERVER_KEY_PATH: Location of the server key.
  • db: Manages the RabbitMQ database. You can perform the following action with this option:
    • flush: Deletes and recreates the RabbitMQ database.
  • client-certs: Manages the client certificates. You can perform the following actions with this option:
    • generate: Generates a client certificate using 'FSRDefaultCA'. Note that if you have deployed your own organization’s signed certificates, then this subcommand will not overwrite your certs, instead a proper message will be displayed and the subcommand will exit.
      You must use the following arguments with this action:
      • --common-name MQ_CLIENT_CERT_COMMON_NAME [--target-dir MQ_CLIENT_CERT_TARGET_DIR]: Common name is used as the username when agent or tenant tries to connect with the secure message exchange. It is recommended that you specify the common name as the name of your agent or tenant. You can optionally also provide the target directory in which you want to store the generated client certificates. By default, the client certificates are generated in the current working directory.
    • mtls: Enables or disables mTLS (mutual TSL). You can perform the following actions using this option:
      • enable: Enables mTLS. If you have enabled mTLS, then you must reconfigure your secure message exchange and provide a pair of exchange event listener client certificates and exchange event listener client keys. For more information, see the Deploying FortiSOAR chapter in the "Deployment Guide." You must also reconfigure all the agents including the tenants' agents by updating the client certificate and client key which are required to connect to the secure message exchange. To reconfigure agents, download and run the agent installer again for the new certificates to be available to the agents.
      • disable: Disables mTLS.
      • status: Retrieves the current status of RabbitMQ mTLS, i.e., it displays either "enabled" or "disabled".
    • truststore: Manages the RabbitMQ truststore. If your client CA certificates are different from the CA certificates of the secure message exchange, then you must add the client CA certificates to the truststore of the secure message exchange for authentication to work.
      You can perform the following actions using this option:
      • add --ca-cert CA_CERT_PATH: Adds a CA certificate to the truststore based on the CA certificate path you have specified.
      • remove --ca-cert-name: Removes a CA certificate from the truststore. You must specify the name of the CA cert to remove it from the truststore. You can use the csadm mq truststore list command to get the name of the CA certificates present in the truststore.
      • list: Lists the CA certificates that are present in the truststore and provides information about them such as name of the CA certificates, expiry of the CA certificates, etc.
      • refresh: Refreshes the truststore. You need refresh the truststore when new certificates are deployed on the secure message exchange.
log

Performs log collection and forwarding of syslogs. You can use the following option and arguments with this subcommand:

  • forward: Forwards FortiSOAR logs to your central log management server (syslog server) that supports a Rsyslog client. For the options that you can use with this subcommand see the CLI commands used for forwarding FortiSOAR logs section. You can also configure forwarding of FortiSOAR logs using the FortiSOAR UI, details of which are in the System Configuration chapter.

  • --collect [LOG_PATH]: Collects logs and bundles them up into a fortisoar-logs.tar.gz file. You must specify the path where the logs should be collected. If you do not specify a path, then the logs will be collected in the current working directory.

  • --password LOG_FILE_PASSWORD: Password-protects the log file, i.e., the password would be required to extract the log file contents. The collected logs are bundled into fortisoar-logs.tar.gz.gpg. Therefore, to collect logs and to password-protect the logs, use the following command:
    csadm log --collect [LOG_PATH][--password LOG_FILE_PASSWORD]

secure-message-exchange

Manages the default secure message exchange server available with a FortiSOAR node. A secure message exchange establishes a secure channel that is used to relay information to the agents or tenant nodes.
Note: For a production setup, it is recommended that you add and configure a separate secure message exchange for handling scale and high availability.
You can use the following options with this subcommand:

  • enable: Enables the secure message exchange on your FortiSOAR instance if you want to use localhost, i.e., the Default (Embedded) secure message exchange to connect to an external agent or in case of a dedicated tenant.
    You must specify the password, which is the admin password that is used for setting up a communication channel for every tenant or agent node that will connect to this FortiSOAR instance using this local secure message exchange. All the other parameters are optional and if they are not specified, then the default values are set. If you do specify the values for any parameter, then the default values are replaced by the user-specified values.
    The following arguments are used with this option:

    • --name: Name that you want to set for the secure message exchange. By default, this is set to Default (Embedded).

    • --user: Admin username that will be used to login to the secure message exchange management console and perform tasks such as configuring tenants and agents on the secure message exchange. Default value is admin.

    • --password: Admin password that will be used to login to the secure message exchange management console.

    • --vhost: Virtual host for running admin commands on the secure message exchange. Default value is cyops-admin.

    • --api-port: RabbitMQ API port that should be enabled for configuring tenants and agents on the secure message exchange. Default value is 15671.

    • --tcp-port: RabbitMQ TCP port that should be enabled for data exchange with tenants and agents. Default value is 5671.

  • disable: Disables the secure message exchange that you had enabled on your FortiSOAR instance for using localhost to connect to an external agent.

  • show-config: Displays the configuration details of your secure message exchange, such as the name of the secure message exchange, username used to login to the secure message exchange, the TCP port and API port that is configured for your secure message exchange, etc.

source-control

Allows import or export of FortiSOAR configurations, such as, MMD and SVT updates along with playbooks and other required configuration changes between systems. This is required for Continuous Integration or Continuous delivery (CICD), which is a pipeline that automates of your software delivery process. The pipeline builds code, runs tests (CI), and safely deploys a new version of the application (CD). You can use the following options with this subcommand:

  • export-config: Exports configurations defined in the source_control.yaml file or a user-defined yaml file. The configuration file is a standard yaml file with sections such as, module, playbook, reports, etc. You can either choose to edit the source_control.yaml file or make a copy of this file, make changes in that file, and then provide the path of the updated file while using the and export-config command. You can either provide value as ‘all’ to export all entities of a particular type or provide a specific entity to export. You can also exclude an entity from being exported by adding it to the ‘exclude’ section
    The export-config command has two optional arguments, a configuration file describing what is to be exported (--config-file [CONFIG_FILE]) and a directory path to save the exported configuration (--export-directory [EXPORT_DIRECTORY]).
    For --config-file [CONFIG_FILE, you can specify the path of the yaml file from where you want to export the configurations. The default location for the configuration file, i.e., the source_control.yml file is /opt/cyops/scripts/csadm/commands/source_control.yaml.
    For --export-directory [EXPORT_DIRECTORY], you can specify the path where you want to export the configuration data. By default, the configurations are exported to /tmp/source_control.
    Once the command completes exporting the configurations, you can copy or move the exported files to the destination system; however, you must preserve the directory structure.
  • import-config: Imports configurations from the yaml files that are located at the specified directory. The import-config command has one optional argument, (--import-directory [IMPORT_DIRECTORY]) in which you can specify the directory from where you want to import the configuration data. By default, the configurations are imported from /tmp/source_control.
services

FortiSOAR services controller (RabbitMQ) functions. You can use the following arguments with this subcommand:

  • --start: Starts all FortiSOAR services in their respective order.

  • --stop: Stops all FortiSOAR services in their respective order.

  • --restart: Restarts all FortiSOAR services in their respective order.

  • --status: Displays the status, i.e., Running or Not Running of all FortiSOAR services.

network

Manages network operations. You can use the following options with this subcommand:

  • ipv6 --enable : Enables the IPv6 protocol on your FortiSOAR system. The system will reboot as part of the execution.
  • set-https-proxy --host<proxy_hostname> --port<proxy_port> --protocol<proxy_protocol> --user<proxy_username> --password<proxy_password>: Configures an https proxy server to serve all https requests from FortiSOAR. To configure an https proxy, you must specify the hostname and the port number of the HTTPS proxy server. You must also specify the protocol to be used to communicate with the HTTPS proxy server. You can also optionally specify the username and password used to access the HTTPS proxy server.
  • set-http-proxy --host<proxy_hostname> --port<proxy_port> --protocol<proxy_protocol> --user<proxy_username> --password<proxy_password>: Configures an http proxy server to serve all http requests from FortiSOAR. To configure an http proxy, you must specify the hostname and the port number of the HTTP proxy server. You must also specify the protocol to be used to communicate with the HTTP proxy server. You can also optionally specify the username and password used to access the HTTP proxy server.

  • list-proxy: Lists the proxies that are configured.

  • set-no-proxy --host<hostname>: Configures a comma-separated list of hostnames that do not require to be routed through a proxy server.
    Note: Review the existing no-proxy list using the list-proxy option. You can add or remove proxies from the existing list by specifying a complete comma-separated list of proxies that you want to configure using the set-no-proxy option.
    For example, if you have added hostname1 to the no-proxy list and you want to add hostname2 to the no-proxy list, then you must run the command as:
    csadm network set-no-proxy --host "hostname1, hostname2"

  • remove-proxy: Removes all the configured proxies, i.e., remove-proxy will remove both the http and https proxies that have been configured.

system

Manages system settings. You can use the following options with this subcommand:

  • disk: Provides Disk management and helps you address disk space issues. You can use this subcommand to extend a logical volume to occupy space that is available in its own volume group or if a new disk is attached, then a single partition is created and the logical volume is expanded to occupy that partition based on the size (GB) you have specified. You can perform the following actions using this option:
    • expand-lv: Expands the specified logical volume. The following arguments can be used with this action:
      • --logical-volume: Specify the name of the logical volume that you want to expand. Running csadm system disk expand-lv --help automatically lists the logical volumes that are available for expansion in the help message.
        Note: You cannot expand 'swap' and 'root' logical volumes using the csadm system disk option.
      • --disk: Name of the disk that you want to use to expand the logical volume. Running csadm system disk expand-lv --help automatically lists the disks that are attached to the system.
        Example of using the --disk argument: The command for expanding the pgsql logical volume to use 10GB of a newly attached disk named 'sdf':
        # csadm system disk expand-lv --logical-volume relations --disk sdf --size 10
      • --use-vg: Specify a value for this argument if you want to extend a logical volume, by the size specified in GBs, to occupy available free space that is available in its own volume group.
        Example of using the --use-vg argument: The command for expanding the pgsql logical volume to consume 100% disk space of the volume group:
        # csadm system disk expand-lv --logical-volume relations --use-vg
        Important: Note the following points with respect to running csadm system disk expand-lv:
        • You must use either the --disk or the --user-vg argument with the expand-lv option.
        • For expansion to take place atleast 1GB free space must be available on the target entry (disk or logical volume). If there is less than 1GB of space available, then csadm system disk expand-lv will exit after displaying an appropriate message.
        • The --disk argument will not operate on a disk that has more than one partition. In this case csadm system disk expand-lv will exit after displaying an appropriate message such as "...This subcommand does not support the automation of handling of multiple partitions due to complications involved....Exiting now"
      • --size: Specify the size in gigabytes (GBs) that will be consumed from the specified disk or volume group that contains the logical volume that you want to expand. You must specify a positive integer for this argument.
        Note: If you do not specify the --size argument, then 100% of the space available on the specified disk or volume group will be used.
        Running this subcommand displays information of the steps that are being performed and also provides information of the sizes of the logical volume and the disk or volume group before and after the expansion.
  • fortimonitor: (Introduced in 7.2.0) Manages FortiSOAR integration with FortiMonitor, i.e., FortiMonitor can be used to monitor your FortiSOAR instance. For more information, see the FortiSOAR integration with FortiMonitor chapter.
    The following options can be used with this subcommand:
    • agent: Manages the FortiMonitor agent.
      The following actions can be performed using this option:
      • install: Installs the FortiMonitor agent on the FortiSOAR instance you want monitored. You must specify the following argument with this option:
        • --customer-key CUSTOMER_KEY: Specify the customer key of your FortiMonitor account.
      • uninstall: Uninstalls the FortiMonitor agent from the monitored FortiSOAR instance.
      • rebuild-metadata: Rebuilds the metadata for a FortiMonitor agent. If you have made any changes to FortiSOAR components to be monitored by FortiMonitor such as adding connector monitoring, then you can run rebuild-metadata to enable the changes to be reflected immediately.
      • show-details: Displays the details such as the agent's uid, the customer and server key, version, etc. of the FortiMonitor agent.

package

Installs, updates, or removes connectors (RPM packages) from your FortiSOAR system.
You must specify the following options with this subcommand:

  • install: Installs an RPM package on your FortiSOAR system. You can use this command to install a connector from the FortiSOAR connector repository. You can use the following arguments with this option:

    • --type {connector} / -t {connector}: Type of package that you want to install, i.e., connector.

    • --name NAME / -n Name: Name of the connector that you want to install.
      Note: The connector name of the connector must begin with cyops-connector. This command installs the latest version of the connector that is currently present in the FortiSOAR connector repository
      For example, to install the Fortinet FortiSIEM connector, run the following command: csadm package install -t connector -n cyops-connector-fortinet-fortisiem.

    • update: Updates an RPM package on your FortiSOAR system. You can use this command to update a connector from the FortiSOAR connector repository. This command also requires the same arguments as the install option, i.e., --type and --name.

    • remove: Removes an RPM package from your FortiSOAR system. This command also requires the same arguments as the install option, i.e., --type and --name.

    • content-hub: Performs synchronization of Content Hub with your FortiSOAR system. The following actions can be performed using this option:

      • sync: Synchronizes Content Hub with your FortiSOAR system. Only a single sync action can be executed at a time, i.e., while the sync action is running in the background, you cannot re-execute the same.
        You can use the following arguments with this action:

        • --force: Forces synchronization of Content Hub with your FortiSOAR system. If you use the --force argument with the sync action, then the sync process that is running in the background is ignored and a fresh sync process gets started.

CLI commands used for forwarding FortiSOAR logs

Use the csadm log forward command to forward FortiSOAR logs to your central log management server (syslog server) that supports a Rsyslog client. You can use the following options with this subcommand:

  • add-config (csadm log forward add config): Adds configuration details for the syslog server to which you want to forward the FortiSOAR. You can use the following arguments with this option:
    • --server: Hostname of the syslog server to which you want to forward the FortiSOAR logs.
    • --port: Port number that you want to use to communicate with the syslog server.
    • --protocol: Protocol that you want to use to communicate with the syslog server. You can specify tcp, udp, or relp.
    • --tls: To securely communicate with the syslog server, set -tls to true.
      If you enable TLS, then in the --ca-cert argument, you must specify the path to the CA certificate PEM file which contains the complete chain of CA certificates including the filename.
      If you have a client certificate for your FortiSOAR client, then in the --client-cert argument, you must specify the path to the client certificate PEM file including the filename, and in the --client-key argument, you must specify the path to the client key PEM file including the filename.
    • --filter: Comma-separated list of filters to specify the type of logs that you want to forward to your syslog server. Valid values are application, audit, none, and by default, all the logs, i.e., application and audit logs are forwarded. If for example, if you want to forward audit logs only then specify --filter=audit.
      If you specify --filter=none, then no logs are forwarded, i.e., log forwarding is temporarily disabled. To enable the log forwarding again, use the update-config option with the --filter argument. For example, csadm log forward update-config –uuid < UUID of configuration > --filter <audit,application>.
      Note: You can define the rules to forward audit logs using the FortiSOAR UI. For more information, see the System Configuration chapter.
    • --config-name: Name of the configuration in which you want to store the log forwarding configuration details.
      Note: Validation checks such as, whether the syslog server is reachable on the specified port etc. are run before adding the syslog server, and the syslog server is added only if the configuration details entered are valid.
  • show-config (csadm log forward show-config): Displays configuration details of the syslog server such as the server's IP address, protocol, TLS information, UUID of the configuration, etc.
  • remove-config (csadm log forward remove-config –uuid <UUID of configuration>): Removes the syslog configuration based on the configuration UUID you have specified. To know the UUID of your configuration use the show-config option.
  • update-config (csadm log forward update-config –uuid < UUID of configuration>): Updates the syslog configuration based on the configuration UUID you have specified. To know the UUID of your configuration use the show-config option. You can update any or all of the options as mention in the add-config subcommand.
    Use the update-config option with the --filter argument, to enable temporarily disabled log forwarding.
Note

You can configure only a single syslog server. If you have already configured a syslog server and you try to add a new one, then FortiSOAR displays appropriate warning messages informing you that a syslog server is already configured, and adding a new syslog server will remove already configured one. Further processing is done based on your response (yes/no) to the messages.

FortiSOAR Admin CLI

An administrator can use FortiSOAR Admin CLI (csadm) to perform various functions such as backing up and restoring data and run various FortiSOAR commands such as starting and stopping services and collecting logs.

Prerequisites

To run csadm you must login as root or have sudo permissions.

FortiSOAR Admin CLI - Usage

Once you type # csadm on the command prompt, the usage and subcommands of the FortiSOAR Admin CLI are displayed as shown in the following image:

FortiSOAR™ Admin CLI command prompt

To perform a particular task in FortiSOAR using csadm, you must type # csadm and then its subcommand and the subcommand’s arguments (if any). For example, to change a hostname use the following command:
# csadm hostname --set [<hostname to be set>]

You can get help for a particular subcommand by running following command:
# csadm <subcommand>
OR
# csadm <subcommand> --help

csadm supports the following subcommands:

Subcommand Description
certs

Generates and deploys your certificates. You can use the following arguments with this subcommand:

  • --deploy: Deploys SSL certificates. For more information, see the Updating the SSL certificates section in the Additional configuration settings for FortiSOAR chapter in the "Deployment Guide."

  • --generate <host name>: Generates and deploys self-signed certificates. You can use the --no-replace-nginx-cert argument with this command, if you do not want to replace your nginx self-signed certificates.

db

Performs operations related to database.
You can use the following arguments with this subcommand:

  • --archival-externalize [ARCHIVAL_DB]: Externalizes your data archival database.

  • --backup [<backup_dir_path>]: Performs a backup of your FortiSOAR system, including backup of both data and configuration files in the directory you have specified.
    From version 6.4.3 onwards, you can optionally use the --exclude-workflow option to exclude all the "Executed Playbook Logs" from the backup. For more information, see the Backing up and Restoring FortiSOAR chapter.

  • --backup-config [<backup_dir_path>]: Performs a backup of only your configuration files in the directory you have specified.

  • --change-passwd: Changes the password of your PostgreSQL database.
    Once you run this command, you will be prompted to enter the password of your choice and confirm the password, which will then update your PostgreSQL database password to the new password.

  • --check-connection: Checks the database connection that is mentioned in the db_external_config.yml file.

  • --restore [<backup_file_path>]: Performs data restore from a locally stored file, whose path you have specified. The default location of the backup file is (/home/csadmin/db_backup/DR_BACKUP_<yyyymmdd_hhmmss>.tgz). For more information, see the Backing up and Restoring FortiSOAR chapter.

  • -encrypt: Generates an encrypted version of the text that you have specified on the prompt. Use this command to generate an encrypted version of the password that you have set for your PostgreSQL database.

  • --externalize: Performs externalization of your FortiSOAR PostgreSQL data. You must provide the path in which you want to save your database backup file. For more information, see the Externalization of your FortiSOAR PostgreSQL database chapter.
    --check-connection: Checks the connection between FortiSOAR and the external PostgreSQL database.

  • --getsize: Displays the size of the primary data and the audit and workflow logs in your database. This enables you to see the current usage and calculate usage over time based on your purging policy.

From version 7.0.0 onwards, you can also backup and restore the data of your external Secure Message Exchange (SME) system, by using the following arguments with the db subcommand:

  • --backup [<backup_dir_path>]: Performs a backup of your external SME system.

  • --restore [<backup_file_path>: Performs data restore for your external SME system from a locally stored file, whose path you have specified. The default location of the backup file is (/home/csadmin/db_backup/DR_BACKUP_<yyyymmdd_hhmmss>.tgz). For more information, see the Backing up and Restoring FortiSOAR chapter.
    Note: All other options of the db option are not applicable to the external SME.

ha Manages your FortiSOAR High Availability cluster. For more information about HA and its commands, see the High Availability support in FortiSOAR chapter.
hostname

Changes the name of the host and Fully Qualified Domain Name (FQDN) based on the parameters you have specified. You can use the following arguments with this subcommand:

  • --set [<hostname>]: If you specify a new hostname, then this changes your current hostname to the new hostname that you have specified, sets up the message broker, regenerates certificates, and restarts FortiSOAR services.
    If you do not specify a hostname, then this sets up the message broker, regenerates certificates using the existing hostname, and restarts FortiSOAR services.
    Note: Before you run this subcommand, you must ensure that the specified hostname is resolvable.

  • --dns-name <DNS_SERVER_IP>: Adds the DNS server entry to the /etc/resolv.conf file.

license

Manages your FortiSOAR license. You can use the following arguments with this subcommand:

  • --get-device-uuid : Retrieves the Device UUID for your FortiSOAR instance.

  • --deploy-enterprise-license <License File Path>: Deploys your FortiSOAR enterprise license. For example, csadm license --deploy-enterprise-license temp/<Serial_No>.lic.

  • --deploy-multi-tenant-license <License File Path>: Deploys your FortiSOAR multitenancy license.

  • --show-details: Displays details of the installed license such as, type of license, Device UUID, expiry date of the license, etc. If you add the [License File Path] parameter to this subcommand, for example --show-details /home/<Serial_No>.lic, then this displays the contents of the license file.

user

Manages your FortiSOAR users. You can use the following options with this subcommand:

  • show-logged-in-users: Displays a list of currently logged in users whose access type is 'Concurrent'.
    The following arguments can be used with this option:
    • --access-type {Named,Concurrent}: Access type, i.e., Named or Concurrent, of the users that you want to include in the list of currently logged in users. For example, if you specify csadm user show-logged-in-users --access-type Named, then the list of 'named' users currently logged into FortiSOAR will be displayed. By default, the access type is set as Concurrent.

    • --limit [1-30]: Last n users who have logged into FortiSOAR. Use this argument to limit the number of users that you want to display in the list of currently logged in users. For example, if you specify csadm user show-logged-in-users --limit 5, then the list will display the last 5 logged in users. By default, the limit is set to 10. You can specify any value between 1 to 30.

  • logout-user --username USERNAME: Forcefully logs out a specific 'Concurrent' user from FortiSOAR; 'Named' users cannot be logged out. You must specify the username argument with this option, i.e., you must include the username of the user you want to log out of FortiSOAR. For example, to log out testuser1, specify csadm user logout-user --username testuser1
mq

FortiSOAR message queue controller (RabbitMQ) functions. You can use the following options with this subcommand:

  • certs: Manages the TLS certificates of the RabbitMQ server.
    You can perform the following actions with this option:

    • generate: Generates the self-signed certificate that will be used for authenticate connections between the secure message exchange (RabbitMQ server) and any client or agent or distributed tenant.
      This generates the signed certificates for the secure message exchange with the CA name as 'FSRDefaultCA'. If you have already deployed your own organization's signed certificate for the secure message exchange, then this subcommand will not overwrite your certs, instead a proper message will be displayed and the subcommand will exit.
      Note: If there are any FSR agents connected to this secure message exchange then you must download and run the agent installer again for the new certificates to be available to the agents.
    • deploy: Deploys the server certificates. You must use the following arguments with this action:
      • --ca-cert MQ_CA_CERT_PATH: Location of the CA certificates. By default, the CA certificate for the FortiSOAR self-signed certificate is present at the following location: /opt/cyops/configs/rabbitmq/ssl/cyopsca/cacert.pem
        Important: The input .pem files must be in the 'Unix' format. You can use dos2unix CLI to convert it to the Unix format.
      • --server-cert MQ_SERVER_CERT_PATH: Location of the server certificates.
      • --server-key MQ_SERVER_KEY_PATH: Location of the server key.
  • db: Manages the RabbitMQ database. You can perform the following action with this option:
    • flush: Deletes and recreates the RabbitMQ database.
  • client-certs: Manages the client certificates. You can perform the following actions with this option:
    • generate: Generates a client certificate using 'FSRDefaultCA'. Note that if you have deployed your own organization’s signed certificates, then this subcommand will not overwrite your certs, instead a proper message will be displayed and the subcommand will exit.
      You must use the following arguments with this action:
      • --common-name MQ_CLIENT_CERT_COMMON_NAME [--target-dir MQ_CLIENT_CERT_TARGET_DIR]: Common name is used as the username when agent or tenant tries to connect with the secure message exchange. It is recommended that you specify the common name as the name of your agent or tenant. You can optionally also provide the target directory in which you want to store the generated client certificates. By default, the client certificates are generated in the current working directory.
    • mtls: Enables or disables mTLS (mutual TSL). You can perform the following actions using this option:
      • enable: Enables mTLS. If you have enabled mTLS, then you must reconfigure your secure message exchange and provide a pair of exchange event listener client certificates and exchange event listener client keys. For more information, see the Deploying FortiSOAR chapter in the "Deployment Guide." You must also reconfigure all the agents including the tenants' agents by updating the client certificate and client key which are required to connect to the secure message exchange. To reconfigure agents, download and run the agent installer again for the new certificates to be available to the agents.
      • disable: Disables mTLS.
      • status: Retrieves the current status of RabbitMQ mTLS, i.e., it displays either "enabled" or "disabled".
    • truststore: Manages the RabbitMQ truststore. If your client CA certificates are different from the CA certificates of the secure message exchange, then you must add the client CA certificates to the truststore of the secure message exchange for authentication to work.
      You can perform the following actions using this option:
      • add --ca-cert CA_CERT_PATH: Adds a CA certificate to the truststore based on the CA certificate path you have specified.
      • remove --ca-cert-name: Removes a CA certificate from the truststore. You must specify the name of the CA cert to remove it from the truststore. You can use the csadm mq truststore list command to get the name of the CA certificates present in the truststore.
      • list: Lists the CA certificates that are present in the truststore and provides information about them such as name of the CA certificates, expiry of the CA certificates, etc.
      • refresh: Refreshes the truststore. You need refresh the truststore when new certificates are deployed on the secure message exchange.
log

Performs log collection and forwarding of syslogs. You can use the following option and arguments with this subcommand:

  • forward: Forwards FortiSOAR logs to your central log management server (syslog server) that supports a Rsyslog client. For the options that you can use with this subcommand see the CLI commands used for forwarding FortiSOAR logs section. You can also configure forwarding of FortiSOAR logs using the FortiSOAR UI, details of which are in the System Configuration chapter.

  • --collect [LOG_PATH]: Collects logs and bundles them up into a fortisoar-logs.tar.gz file. You must specify the path where the logs should be collected. If you do not specify a path, then the logs will be collected in the current working directory.

  • --password LOG_FILE_PASSWORD: Password-protects the log file, i.e., the password would be required to extract the log file contents. The collected logs are bundled into fortisoar-logs.tar.gz.gpg. Therefore, to collect logs and to password-protect the logs, use the following command:
    csadm log --collect [LOG_PATH][--password LOG_FILE_PASSWORD]

secure-message-exchange

Manages the default secure message exchange server available with a FortiSOAR node. A secure message exchange establishes a secure channel that is used to relay information to the agents or tenant nodes.
Note: For a production setup, it is recommended that you add and configure a separate secure message exchange for handling scale and high availability.
You can use the following options with this subcommand:

  • enable: Enables the secure message exchange on your FortiSOAR instance if you want to use localhost, i.e., the Default (Embedded) secure message exchange to connect to an external agent or in case of a dedicated tenant.
    You must specify the password, which is the admin password that is used for setting up a communication channel for every tenant or agent node that will connect to this FortiSOAR instance using this local secure message exchange. All the other parameters are optional and if they are not specified, then the default values are set. If you do specify the values for any parameter, then the default values are replaced by the user-specified values.
    The following arguments are used with this option:

    • --name: Name that you want to set for the secure message exchange. By default, this is set to Default (Embedded).

    • --user: Admin username that will be used to login to the secure message exchange management console and perform tasks such as configuring tenants and agents on the secure message exchange. Default value is admin.

    • --password: Admin password that will be used to login to the secure message exchange management console.

    • --vhost: Virtual host for running admin commands on the secure message exchange. Default value is cyops-admin.

    • --api-port: RabbitMQ API port that should be enabled for configuring tenants and agents on the secure message exchange. Default value is 15671.

    • --tcp-port: RabbitMQ TCP port that should be enabled for data exchange with tenants and agents. Default value is 5671.

  • disable: Disables the secure message exchange that you had enabled on your FortiSOAR instance for using localhost to connect to an external agent.

  • show-config: Displays the configuration details of your secure message exchange, such as the name of the secure message exchange, username used to login to the secure message exchange, the TCP port and API port that is configured for your secure message exchange, etc.

source-control

Allows import or export of FortiSOAR configurations, such as, MMD and SVT updates along with playbooks and other required configuration changes between systems. This is required for Continuous Integration or Continuous delivery (CICD), which is a pipeline that automates of your software delivery process. The pipeline builds code, runs tests (CI), and safely deploys a new version of the application (CD). You can use the following options with this subcommand:

  • export-config: Exports configurations defined in the source_control.yaml file or a user-defined yaml file. The configuration file is a standard yaml file with sections such as, module, playbook, reports, etc. You can either choose to edit the source_control.yaml file or make a copy of this file, make changes in that file, and then provide the path of the updated file while using the and export-config command. You can either provide value as ‘all’ to export all entities of a particular type or provide a specific entity to export. You can also exclude an entity from being exported by adding it to the ‘exclude’ section
    The export-config command has two optional arguments, a configuration file describing what is to be exported (--config-file [CONFIG_FILE]) and a directory path to save the exported configuration (--export-directory [EXPORT_DIRECTORY]).
    For --config-file [CONFIG_FILE, you can specify the path of the yaml file from where you want to export the configurations. The default location for the configuration file, i.e., the source_control.yml file is /opt/cyops/scripts/csadm/commands/source_control.yaml.
    For --export-directory [EXPORT_DIRECTORY], you can specify the path where you want to export the configuration data. By default, the configurations are exported to /tmp/source_control.
    Once the command completes exporting the configurations, you can copy or move the exported files to the destination system; however, you must preserve the directory structure.
  • import-config: Imports configurations from the yaml files that are located at the specified directory. The import-config command has one optional argument, (--import-directory [IMPORT_DIRECTORY]) in which you can specify the directory from where you want to import the configuration data. By default, the configurations are imported from /tmp/source_control.
services

FortiSOAR services controller (RabbitMQ) functions. You can use the following arguments with this subcommand:

  • --start: Starts all FortiSOAR services in their respective order.

  • --stop: Stops all FortiSOAR services in their respective order.

  • --restart: Restarts all FortiSOAR services in their respective order.

  • --status: Displays the status, i.e., Running or Not Running of all FortiSOAR services.

network

Manages network operations. You can use the following options with this subcommand:

  • ipv6 --enable : Enables the IPv6 protocol on your FortiSOAR system. The system will reboot as part of the execution.
  • set-https-proxy --host<proxy_hostname> --port<proxy_port> --protocol<proxy_protocol> --user<proxy_username> --password<proxy_password>: Configures an https proxy server to serve all https requests from FortiSOAR. To configure an https proxy, you must specify the hostname and the port number of the HTTPS proxy server. You must also specify the protocol to be used to communicate with the HTTPS proxy server. You can also optionally specify the username and password used to access the HTTPS proxy server.
  • set-http-proxy --host<proxy_hostname> --port<proxy_port> --protocol<proxy_protocol> --user<proxy_username> --password<proxy_password>: Configures an http proxy server to serve all http requests from FortiSOAR. To configure an http proxy, you must specify the hostname and the port number of the HTTP proxy server. You must also specify the protocol to be used to communicate with the HTTP proxy server. You can also optionally specify the username and password used to access the HTTP proxy server.

  • list-proxy: Lists the proxies that are configured.

  • set-no-proxy --host<hostname>: Configures a comma-separated list of hostnames that do not require to be routed through a proxy server.
    Note: Review the existing no-proxy list using the list-proxy option. You can add or remove proxies from the existing list by specifying a complete comma-separated list of proxies that you want to configure using the set-no-proxy option.
    For example, if you have added hostname1 to the no-proxy list and you want to add hostname2 to the no-proxy list, then you must run the command as:
    csadm network set-no-proxy --host "hostname1, hostname2"

  • remove-proxy: Removes all the configured proxies, i.e., remove-proxy will remove both the http and https proxies that have been configured.

system

Manages system settings. You can use the following options with this subcommand:

  • disk: Provides Disk management and helps you address disk space issues. You can use this subcommand to extend a logical volume to occupy space that is available in its own volume group or if a new disk is attached, then a single partition is created and the logical volume is expanded to occupy that partition based on the size (GB) you have specified. You can perform the following actions using this option:
    • expand-lv: Expands the specified logical volume. The following arguments can be used with this action:
      • --logical-volume: Specify the name of the logical volume that you want to expand. Running csadm system disk expand-lv --help automatically lists the logical volumes that are available for expansion in the help message.
        Note: You cannot expand 'swap' and 'root' logical volumes using the csadm system disk option.
      • --disk: Name of the disk that you want to use to expand the logical volume. Running csadm system disk expand-lv --help automatically lists the disks that are attached to the system.
        Example of using the --disk argument: The command for expanding the pgsql logical volume to use 10GB of a newly attached disk named 'sdf':
        # csadm system disk expand-lv --logical-volume relations --disk sdf --size 10
      • --use-vg: Specify a value for this argument if you want to extend a logical volume, by the size specified in GBs, to occupy available free space that is available in its own volume group.
        Example of using the --use-vg argument: The command for expanding the pgsql logical volume to consume 100% disk space of the volume group:
        # csadm system disk expand-lv --logical-volume relations --use-vg
        Important: Note the following points with respect to running csadm system disk expand-lv:
        • You must use either the --disk or the --user-vg argument with the expand-lv option.
        • For expansion to take place atleast 1GB free space must be available on the target entry (disk or logical volume). If there is less than 1GB of space available, then csadm system disk expand-lv will exit after displaying an appropriate message.
        • The --disk argument will not operate on a disk that has more than one partition. In this case csadm system disk expand-lv will exit after displaying an appropriate message such as "...This subcommand does not support the automation of handling of multiple partitions due to complications involved....Exiting now"
      • --size: Specify the size in gigabytes (GBs) that will be consumed from the specified disk or volume group that contains the logical volume that you want to expand. You must specify a positive integer for this argument.
        Note: If you do not specify the --size argument, then 100% of the space available on the specified disk or volume group will be used.
        Running this subcommand displays information of the steps that are being performed and also provides information of the sizes of the logical volume and the disk or volume group before and after the expansion.
  • fortimonitor: (Introduced in 7.2.0) Manages FortiSOAR integration with FortiMonitor, i.e., FortiMonitor can be used to monitor your FortiSOAR instance. For more information, see the FortiSOAR integration with FortiMonitor chapter.
    The following options can be used with this subcommand:
    • agent: Manages the FortiMonitor agent.
      The following actions can be performed using this option:
      • install: Installs the FortiMonitor agent on the FortiSOAR instance you want monitored. You must specify the following argument with this option:
        • --customer-key CUSTOMER_KEY: Specify the customer key of your FortiMonitor account.
      • uninstall: Uninstalls the FortiMonitor agent from the monitored FortiSOAR instance.
      • rebuild-metadata: Rebuilds the metadata for a FortiMonitor agent. If you have made any changes to FortiSOAR components to be monitored by FortiMonitor such as adding connector monitoring, then you can run rebuild-metadata to enable the changes to be reflected immediately.
      • show-details: Displays the details such as the agent's uid, the customer and server key, version, etc. of the FortiMonitor agent.

package

Installs, updates, or removes connectors (RPM packages) from your FortiSOAR system.
You must specify the following options with this subcommand:

  • install: Installs an RPM package on your FortiSOAR system. You can use this command to install a connector from the FortiSOAR connector repository. You can use the following arguments with this option:

    • --type {connector} / -t {connector}: Type of package that you want to install, i.e., connector.

    • --name NAME / -n Name: Name of the connector that you want to install.
      Note: The connector name of the connector must begin with cyops-connector. This command installs the latest version of the connector that is currently present in the FortiSOAR connector repository
      For example, to install the Fortinet FortiSIEM connector, run the following command: csadm package install -t connector -n cyops-connector-fortinet-fortisiem.

    • update: Updates an RPM package on your FortiSOAR system. You can use this command to update a connector from the FortiSOAR connector repository. This command also requires the same arguments as the install option, i.e., --type and --name.

    • remove: Removes an RPM package from your FortiSOAR system. This command also requires the same arguments as the install option, i.e., --type and --name.

    • content-hub: Performs synchronization of Content Hub with your FortiSOAR system. The following actions can be performed using this option:

      • sync: Synchronizes Content Hub with your FortiSOAR system. Only a single sync action can be executed at a time, i.e., while the sync action is running in the background, you cannot re-execute the same.
        You can use the following arguments with this action:

        • --force: Forces synchronization of Content Hub with your FortiSOAR system. If you use the --force argument with the sync action, then the sync process that is running in the background is ignored and a fresh sync process gets started.

CLI commands used for forwarding FortiSOAR logs

Use the csadm log forward command to forward FortiSOAR logs to your central log management server (syslog server) that supports a Rsyslog client. You can use the following options with this subcommand:

  • add-config (csadm log forward add config): Adds configuration details for the syslog server to which you want to forward the FortiSOAR. You can use the following arguments with this option:
    • --server: Hostname of the syslog server to which you want to forward the FortiSOAR logs.
    • --port: Port number that you want to use to communicate with the syslog server.
    • --protocol: Protocol that you want to use to communicate with the syslog server. You can specify tcp, udp, or relp.
    • --tls: To securely communicate with the syslog server, set -tls to true.
      If you enable TLS, then in the --ca-cert argument, you must specify the path to the CA certificate PEM file which contains the complete chain of CA certificates including the filename.
      If you have a client certificate for your FortiSOAR client, then in the --client-cert argument, you must specify the path to the client certificate PEM file including the filename, and in the --client-key argument, you must specify the path to the client key PEM file including the filename.
    • --filter: Comma-separated list of filters to specify the type of logs that you want to forward to your syslog server. Valid values are application, audit, none, and by default, all the logs, i.e., application and audit logs are forwarded. If for example, if you want to forward audit logs only then specify --filter=audit.
      If you specify --filter=none, then no logs are forwarded, i.e., log forwarding is temporarily disabled. To enable the log forwarding again, use the update-config option with the --filter argument. For example, csadm log forward update-config –uuid < UUID of configuration > --filter <audit,application>.
      Note: You can define the rules to forward audit logs using the FortiSOAR UI. For more information, see the System Configuration chapter.
    • --config-name: Name of the configuration in which you want to store the log forwarding configuration details.
      Note: Validation checks such as, whether the syslog server is reachable on the specified port etc. are run before adding the syslog server, and the syslog server is added only if the configuration details entered are valid.
  • show-config (csadm log forward show-config): Displays configuration details of the syslog server such as the server's IP address, protocol, TLS information, UUID of the configuration, etc.
  • remove-config (csadm log forward remove-config –uuid <UUID of configuration>): Removes the syslog configuration based on the configuration UUID you have specified. To know the UUID of your configuration use the show-config option.
  • update-config (csadm log forward update-config –uuid < UUID of configuration>): Updates the syslog configuration based on the configuration UUID you have specified. To know the UUID of your configuration use the show-config option. You can update any or all of the options as mention in the add-config subcommand.
    Use the update-config option with the --filter argument, to enable temporarily disabled log forwarding.
Note

You can configure only a single syslog server. If you have already configured a syslog server and you try to add a new one, then FortiSOAR displays appropriate warning messages informing you that a syslog server is already configured, and adding a new syslog server will remove already configured one. Further processing is done based on your response (yes/no) to the messages.