5 1 0:SEP sesam CLI

From SEPsesam
Revision as of 11:49, 16 October 2023 by Jus (talk | contribs) (fixing links)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


Welcome to the latest SEP sesam documentation version 5.1.0 Apollon. For previous documentation version(s), check documentation archive.


Overview


The SEP sesam CLI reference contains an overview of the SEP sesam CLI commands and their usage. The use of SEP sesam CLI is version dependent. If you are using an older SEP sesam version, see SEP sesam CLI in v. Jaglion or SEP sesam CLI in v. Beefalo.

The SEP sesam command line interface (CLI) is a utility that provides an alternative way to execute SEP sesam commands in UNIX and Windows environments. SEP sesam command line interface provides two CLI components: the administration utility SEP sesam CLI and the client utility SBC CLI. The latter is used to back up and restore data locally on the host.

The SEP sesam CLI administration utility provides all the functions available via SEP sesam graphical management interface and also additional CLI commands that are not available in the GUI. Note that different commands may be available depending on your SEP sesam license.

SEP sesam CLI commands can be used to install and configure a SEP sesam environment automatically without a GUI. They enable administrators to access the SEP sesam database and manage the entire SEP sesam environment, e.g., to install, configure and manage SEP sesam Servers and Clients centrally without a GUI. Every CLI command (except a native SQL statement) checks and follows the internal structure and dependencies of the SEP sesam database.

Note
Some changes have been made to CLI for version ≥ Jaglion compared to the previous version. See below SEP sesam CLI usage for details.

Features

  • Automatic configuration of SEP sesam environments after installation (e.g., on implementation)
  • Modify SEP sesam configuration without using the SEP sesam GUI
  • Script-based mass installation and configuration (e.g., provider environment)
  • Perform tests for installation and configuration in SEP sesam environments
  • Get SEP sesam status, log and version information
  • Determine SEP sesam object information for further use in other programs

Running CLI commands

You must have SEP sesam administrator privileges to run SEP sesam CLI commands and use the command prompt as an administrator. All commands are run from the <SESAM_ROOT>/bin/sesam/ directory. If you want to execute SEP sesam commands globally (and not from the actual run directory), set the SEP sesam profile as described in What happens when I set a profile?.

Understanding the command structure

The general SEP sesam syntax for a CLI command is:

sm_cmd [BASE PARAMETERS] <command> <object> [OPTIONS]

where the following information is provided for each command

  • sm_cmd: A command line tool that invokes the command line interface.
  • Usage: The actual syntax of the command, including arguments.
  • Description: A brief summary of what the command does.
  • Arguments: The definition of the options used in the command.
  • Example: An example of how to use the specified command and its options.
sm_cmd base parameters
BASE PARAMETERS:
       -F [param]     Set output status messages (including error) in JSON format
       -P [param]     Password to connect with (old: -password)
       -S [param]     Server to connect to (old: -s -server)
       -U [param]     User to connect with (old: -user)
       -a [0|1]       Show all hidden parameters (old: -showall)
       -drymode [0|1] dryMode (old: -drymode)
       -f [param]     Read commands from file in this path (old: -path)
       -h [0|1]       Print help (old: -help)
       -p [param]     Port to use (old: -port)
       -t [param]     Connection timeout in seconds (Defaults to 0 [== off]). (old: -timeout)
       -v [param]     The verbose level
       -z [param]     Certificate file used for user authentication (X.509, PEM) (old: -certificate)

Command conventions

The parameters for a command are order-dependent and may include required and optional values or keyword choices, depending on how the information is bracketed. Required parameters are marked with an asterisk (*). An example is provided below.

| vertical bar
Separates the choices between two or more options or arguments.
[ ] square brackets
Indicate optional values.
< > angle brackets
Indicate that the enclosed element is mandatory.
Example:
sm_cmd <get|list|add|modify|start|remove> taskevent [OPTIONS...]

One of the actions bracketed with < > symbols, in this case <get|list|add|modify|start|remove>, is mandatory, while the [OPTIONS...] are enclosed with [ ] symbols, therefore the requested information is optional. The following options are available for our example taskevent command.

  sm_cmd start taskevent ID [OPTIONS...]
    Immediately start the given backup task or task group.
    Task (-j) or task group (-G) must be set

       -@ [param]     follow up (command to be run after the event completes)
       -B [date]      start date and time, supported date format is <yyyy-MM-dd hh:mm:ss>
       -G [param]     task group
       -K [0|1]       blocking date
       -M [param]     subsequent migration task
       -R [0|1]       restart flag
       -S [param]     name of the interface
       -Z [param]     time frame after which the scheduled event will be canceled in days and/or hours <hh:mm> (stop task if it runs longer than, e.g. 48:00)
       -d [number]    drive number
       -e [0|1]       enforce full backup if last full backup has failed (if -l is not equal to Full or Copy)
       -j [param]     backup task
       -l [param]     backup level: <C = Copy|F = Full|D = Differential|I = Incremental>
       -m [param]     media pool
       -p [number]    event priority (lowest: 1 (default), highest: 99)
       -s [0|1]       source-side deduplication
       -x [param]     schedule that triggered the task event
       -z [param]     duration of start time frame (e.g. 06:00) which specifies the amount of time in hours for which an event can be in the queue

Suppose we want to run a backup event for a backup task named win-cli_c_drive and use the target media pool (to which the data is backed up) MP_disk_week. The command would look like this:

sm_cmd start taskevent -j win-cli_c_drive -m MP_disk_week

Getting help

To list all available options, use the main help sm_cmd help. To show help for a specific object, use sm_cmd help <object>, e.g., sm_cmd help client.

Common action commands

The action command is used to perform an action or retrieve information/status about the resource. Most SEP sesam CLI resources have the following action commands:

get
The get command retrieves information about the resource or the currently defined operation.
list
The list command returns a list of objects for the specified resource. If the optional <object_name_or_id> is also specified, the results are filtered by this value.
add
The add command creates a new object or event. If the optional <object_name_or_id> is also specified, then the objects are created according to the specified value.
modify
The modify command changes an existing resource based on the specified object options.
remove
The remove command deletes the specified object.

Before you start

SEP sesam CLI is a very powerful command-line tool. You should be aware of its implications on your entire environment before you start using it.

Recommendations for using SEP sesam CLI

  • SEP sesam's optional command line commands change the SEP sesam database directly. Therefore all command line entries should be checked and verified!
  • SEP sesam executes the commands immediately when the <Enter>/<Return> key is pressed. This means that entries cannot be corrected, as is the case with the SEP Sesam GUI. It is extremely important that you are familiar with CLI and use it wisely to avoid a system failure of the backup environment. Note that an incorrect entry may result in a complete data loss or other damage to the database. Such errors may void the warranty of your SEP sesam license agreement.
Note
Before you start scripting with SEP sesam CLI, you should familiarize yourself with the SEP sesam environment. Read the SEP sesam documentation carefully and work on the SEP sesam installation and configuration to understand how the SEP sesam objects work together.


SEP sesam CLI usage

Command Description
sm_cmd <get|list|add|modify|remove|send> account Create and administer email accounts.
sm_cmd <get|list|remove|check> acl List or delete access control list (ACL).
sm_cmd list allevent List all SEP sesam events.
sm_cmd list allresult List all results within the specified time period.
sm_cmd <remove|start>backup Start the backup task or the backups of the task group.
sm_cmd clear cache Clear the entire server cache.
sm_cmd <get|list|add|modify|remove> calendar Create and administer calendars.
sm_cmd <get|list|add|modify|remove> calendarevent Create and administer calendar events.
sm_cmd <download|show> calendarsheet Display or download calendar information.
sm_cmd <get|list|add|modify|remove|dir> client Create and administer clients.
sm_cmd <get|list|add|modify|rename|start|remove> command Create and administer commands.
sm_cmd <get|list|add|modify|start|remove> commandevent Create and administer command events.
sm_cmd <get|list|add|modify|enable|disable|link|unlink|remove> credential Configure and administer credentials.
sm_cmd <download|show> current Display or download the current drive information.
sm_cmd <get|list|add|modify|remove> datastore Create and administer data stores.
sm_cmd <get|list|add|modify|remove> default Configure and administer default keys.
sm_cmd dir <argument> List all specified clients, elements, VMs, etc.
sm_cmd <get|list|add|modify|remove|start|mount|dismount|unload> drive Create and administer drives.
sm_cmd <get|list|add|modify|remove> drivegroup Create and administer drive groups.
sm_cmd <get|list|add|modify|remove> group Create and administer user groups.
sm_cmd <get|list|add|modify|remove> interface Create and administer interfaces.
sm_cmd start inventory Start archive adjustment.
sm_cmd <show|update|report> license Check the SEP sesam license information and update the license.
sm_cmd <get|list|add|modify|remove|load|unload|import|export> loader Create and administer loaders.
sm_cmd <get|list|add|modify|remove> loaderdevice Create and administer loader devices.
sm_cmd <get|list|add|modify|remove> location Create and administer locations.
sm_cmd <download|upload|show|list> log Monitor and download log files from the server, or upload logs directly to the SEP Customer Experience server.
sm_cmd <get|list|add|modify|remove> media Create and administer storage media.
sm_cmd <get|list|add|modify|remove> mediapool Create and administer media pools.
sm_cmd <get|list|add|modify|start|init|remove> mediapoolevent Create and administer media events.
sm_cmd list mediaresult List all media results, filtered by list options.
sm_cmd migrate Start a migration immediately.
sm_cmd <get|list|add|modify|remove|start> migration Create and administer migration events.
sm_cmd <list|restart|cancel> migrationresult Check, restart or cancel migration events.
sm_cmd <get|list|add|modify|remove> migrationtask Create and administer migration tasks.
sm_cmd <get|list|add|modify|start|remove> newdayevent Create and administer NEWDAY events.
sm_cmd <get|list|add|modify> notification Create and modify notifications.
sm_cmd <get|list> opersystem List a specific OS or all operating systems.
sm_cmd render Renders the specified template.
sm_cmd <get|list|add|modify|remove|start|cancel> replication Create and administer replication events.
sm_cmd replicate Start replication, can be used as shortcut for sm_cmd start replication.
sm_cmd <list|cancel> replicationresult List and cancel replication events.
sm_cmd <get|list|add|modify|remove> replicationtask Create and administer replication tasks.
sm_cmd <list|restart> Check and restart backups/migrations.
sm_cmd <get|list|add|modify|restore|start|remove|cancel> restore Create and administer restore events.
sm_cmd <list|cancel> restoreresult Check and cancel restore events.
sm_cmd <get|list|add|modify|restore|start|remove> restoreevent Create and administer restore events.
sm_cmd <get|list|add|modify|start|remove> restoretask Create and administer restore tasks.
sm_cmd <get|list> result Monitor the results according to set filters (e.g., clients, tasks).
sm_cmd <dir> saveset Browse a saveset.
sm_cmd remove savesets Delete specified savesets.
sm_cmd <get|list|add|modify|rename|remove|start> schedule Configure and administer schedules.
sm_cmd stop server Stop the SEP sesam server. Note that this command can be executed only from the SEP sesam server console.
sm_cmd <download|show> services Monitor and download different files or logs.
sm_cmd list session List all active sessions.
sm_cmd sql Execute an SQL query and define its output format.
sm_cmd start <task|restore|migration|command> Start an event.
sm_cmd start report Create a customized report.
sm_cmd <get|list|add|modify|start|remove> task Create and administer tasks.
sm_cmd <get|list|add|modify|backup|remove|restart> taskevent Create and administer task events.
sm_cmd add taskgen Generate tasks according to the specified task type.
sm_cmd <get|list|add|modify|start|remove> taskgroup Create and administer task groups.
sm_cmd modify taskgroup {task_group} -j {task}[,{task}] Modify task group relations. Example: sm_cmd modify taskgroup taskgroup1 -j task1,task2
sm_cmd <download|list> update Monitor and download JAR (.jar) updates.
sm_cmd <get|list|add|modify|remove|reset> user Create and administer users.
sm_cmd show version Display the SEP sesam Server and Client package version.
sm_cmd <resetcbt|check|generate|list> vsphere Reset CBT, monitor vSphere environment and generate vSphere task group.


SEP sesam CLI for Apollon: changes

Some changes were made in the CLI for the Apollon and Apollon V2 versions.

New commands
  • A backup can be deleted using remove backup
  • A saveset can be deleted using remove savesets
  • A command event can be started with start commandevent
  • A command can be renamed using sm_cmd rename command <old name> <new name>
  • A schedule can be renamed using sm_cmd rename schedule <old name> <new name>
  • Replication can be started with replicate, the shortcut is added as an alternative to start replication (for example: sm_cmd replicate REP_Si3_month_to_SI3_RDS).
  • Logs can be uploaded directly to the SEP Customer Experience server using upload log.
Backup
  • When restarting a backup using sm_cmd restart -s <saveset id>, the CLI now prints the new saveset ID instead of the backup event ID.
  • Added reference type continue to continue cancelled backups
Client administration
  • Clients can be exported with full data on credentials, on import the credentials will be recreated.
  • Credentials can be exported and imported.
Commands/Command events
  • A command event can now be deleted either by name or by ID
  • New parameter -A (abort command) for add commandevent
Datastores
  • When configuring a new datastore, the running operations of the existing datastores are no longer terminated. A new datastore can be added without re-initializing all drive queues.
  • When creating a new datastore, the drive number of the first drive of the datastore is now printed in addition to the datastore name.
  • When adding or modifying a datastore, the data store options can be now set using -A "<options>".
  • When adding a new datastore, two drives are created with the data store by default. The parameter -D 0 prevents creating the second drive.
  • When removing a datastore, a new option -F <n> is available to remove the datastore metadata only (-F 0) or the datastore metadata and data files (-F 1). Note that -F 1 is the default setting and the datastore is removed with all metadata and data files by default.
  • For datastores the option -o (for command sm_config_drive) changed from boolean to a number:
   -o 0: do not start sm_config_drives at all
   -o 1: start sm_config_drives <dn> CREATE-DS
   -o 2: start sm_config_drives <dn>
   -o 3: start sm_config_drives
Interfaces
  • New parameter -c (client) for command list interface
  • New parameter -i (interface order) for command add interface
  • New command modify interface with parameters -i (interface order) and -n (new name in case of renaming interface)
Media Pools
  • New parameter -v for ADD and MODIFY commands that set the failover media pool
Migrations
  • Removed parameter -e (backup state) from ADD and MODIFY commands as it is set in migration tasks
Replication
  • New parameter -s to replicate/start replication a single saveset, for example: sm_cmd replicate -s SC20220728132336417@xnlwBh7mGUh -M MP_Si3_RDS)
  • New parameter -m to specify the source media pool, for example: m_cmd replicate -m MP_Si3_month -M MP_Si3_RDS
Restore
  • When starting a restore, the required backup level can be specified for the restore command sm_cmd restore -j <task name> -y C.
  • The saveset ID of a migrated backup can be specified sm_cmd restore -s <saveset ID of migrated backup>.
  • Modified parameters of start/restore:
    • Renamed parameter B (relative start date) to I
    • Renamed parameter E (relative end date) to J
    • Removed parameter K, it was no longer used
Schedules
  • Removed all parameters except -p(priority) and -s (start time) from the start command, as they are not needed for starting a schedule.
  • Parameters start date, end date and start time must be valid date/time strings. If not, an error is printed.
Task Events
  • New parameter -v for add and modify commands to set the failover task event
  • Removed parameter -Z (lifetime) for add and modify commands
Common
  • When the SEP sesam REST server is running HTTPS with a real certificate (not self-signed), the CLI can verify the SSL certificate during the SSL connection handshake. A parameter -Z <absolute path to CA key> has been added to pass in the CA verification key. Alternatively, the CA verification key can also be added to the Java global key store.
  • MODIFY creates a new default when no default with the given key already exists


See also

SBC CLIUseful SEP sesam CommandsSEP sesam GUI

Copyright © SEP AG 1999-2024. All rights reserved.
Any form of reproduction of the contents or parts of this manual is allowed only with the express written permission from SEP AG. When compiling and designing user documentation SEP AG uses great diligence and attempts to deliver accurate and correct information. However, SEP AG cannot issue a guarantee for the contents of this manual.