5 1 0:Creating a Command Event

Overview

Commands in SEP sesam enable you to run specific functions on a SEP sesam Client. You can create command definitions, which can be used to perform or automate different actions in SEP sesam environment.

To run a command, create a command event and then start the command event immediately or schedule the event for automatic execution.

Prerequisites

• A user must be authorized to run the commands on a specific client.
• By default, only commands entered in the system directory at <SESAM_ROOT>/bin/sesam can be executed. If you want to allow starting commands in other directories, see section Setting permissions to run commands.

How it works

To run different commands in SEP sesam environment, you must first create a command definition. Main components of a command definition are the command and the additional parameters. A command event is then used to execute a defined command, either as a one-time event, or a scheduled event. A command event complements the command definition. A command definition can contain just the basic arguments, and the command event can specify the additional options to specialize the command.

For example, you want to create a command to obtain disk usage of a location. the command syntax is as follows:

sm_client du -m d <path>

You can create the following command definition to check disk usage of drive C:

sm_client du -m d C:

Then you can create a command event that will run this command either once, or periodically.

If you want to check disk usage of more than one drive, you can create the following basic command definition:

 sm_client du -m d

Then you can create command events for all drives you want to check by reusing the command and specifying additional parameters. You can have one command event for drive C: and another one for drive D: where you add C: in the additional parameters for the first command event and D: in the additional parameters for the second command event.

Command definition can include the user, under which the command will be run, and the client, on which the command will run. Note that in case the user and client is set both in command definition and command event, the settings in command event take precedense and override the settings in the command definition.

In command definition, a cancellation command can be specified. This command is executed when the original command gets cancelled. Abort command enables you to specify a command that can end the interrupted execution of a command properly. For example, you can create an appropriate RMAN script and set it as abort command to end the running RMAN process if the initial Oracle RMAN command is cancelled.

In addition, in abort commands you can use placeholders $PID, $SID and $CMD (you can also use {PID}, {SID}, and {CMD} in shell scripts). They will get replaced with the process ID, the session ID, or the command parameters of the original command. Note that placeholder $SID can contain several session IDs, separated by a comma and without spaces in between.

An example abort command:

sbc -k -l 2 -P $PID

where $PID will get replaced with the process ID.

Creating a command definition

To create a command definition, follow the steps below:

1. From Main Selection -> Tasks -> Commands, click New Command. The New Command window opens.
2. Define the following:
   • Name: Enter the name for a new command.
   • User: Enter a user name of the user with sufficient access to execute the command on the client.
   • Command: Enter the complete command (and parameters, if required), e.g., eventlog.ps1.
3. Optionally, you can define the following:
   • Client: Select a client, on which the command will be executed.
   • Additional Parameter: Enter additional parameters for the command, which are appended to the end of the command line. Note that additional parameters for a command can also be specified when creating a command event.
   • Cancellation Command: Cancellation command will be run if the command event is cancelled during its execution. You can pass special parameters to the abort command using the placeholders $PID, $SID and $CMD. They will be replaced with the process ID, the session ID, or the command parameters of the original command. For example, sbc -k -l 2 -P $PID becomes sbc -k -l 2 -P 123456.For more information see section on abort command above.
   • Note: You can add a note or comment.
4. Click OK to create your command definition. You can review your commands and assigned events, trigger commands to start immediately, or delete them by right-clicking the selected command.

Creating a command event

You can create a command event in two ways:

• From Command view (Main Selection -> Tasks -> Commands)
• From Schedules view (Main Selection -> Scheduling -> Schedules)

Note that in the Schedules view you can also change the settings for the schedule. In the Command view you can review schedule settings, but you cannot modify them.

To create a new command event from the Command view, follow the steps below:

1. From Main Selection -> Tasks -> Commands, select the command for which you want to add a command event. Then right-click the selected command and click New Command Event. The New Command Event window opens.
   Note that by default the command event will be added to a schedule. To configure a new schedule, see Creating a Schedule.
2. In Parameter tab, specify the following settings:
• Priority: Optionally, define a priority for the command event. SEPuler always executes schedules with higher priority first. The default priority level is 1, which is the lowest priority (the highest is 99). The exception is priority 0, which overrides all other priorities and is always executed. For details, see Event Priority.
• Blocking date: This should be used in conjunction with high priority for special events. When this check box is selected, lower priority events of the same type are blocked, ensuring that the command event is processed if other command events are also scheduled at the same time. See Blocking Events.
• Name: Select the name of the command from the drop-down list (if necessary). When selected, the full command is displayed in the Preview field below.
• Client: Select a client on which to execute the command.
• User: Enter the user name of a user who has sufficient rights to execute the command on the client.
• Retention time: Specify how long (in days) to retain the command event results and logs (default 30).
• Additional Parameter: Optionally add additional parameters to the command, which will be appended to the end of the command. In case command definition already contains additional parameters, they are retained in read-only mode and the event parameters are appended to the end. You can see the full command in the Preview field below.
• Follow up: Optionally, use this field to configure a follow-up event to be started on the SEP sesam Server once the command event has completed. For details, see Creating Follow-up Events.
  
3. To schedule the command event, click Schedule tab. In the Name drop-down list, select the schedule, to which you want to add the command event. If you do not want to add this event to a schedule, select Without Schedule.
   
4. Click OK to create your command event. You can review your commands and assigned events, trigger events to start immediately, or delete them by right-clicking the selected event.

	Tip
	You can also create a command event from Schedule view. From Main Selection -> Scheduling -> Schedules, right-click the schedule to which you want to add a command event and then select New Command Event.

Immediate start

To override the scheduled start time for an event or to trigger the command or command event to run at custom time, you can use the Immediate Start option.

From Main Selection -> Tasks -> Commands, right-click a command or a command event you want to trigger and then click Immediate Start. The procedure is slightly different for commands and command events.

Triggering a command event

When you trigger the command event, you can select the priority for the event and select the start time. You can start the command event now, or define a custom start date and time to postpone the immediate start to a more convenient time.

Triggering a command

When you trigger the command, you can review and modify the command settings, specifying any additional parameters or options as required. If you want to postpone the start to a more convenient time, you can switch to Execution Time tab and define a custom start date and time.

Cancelling a command event

In case you want to cancel a running command event, go to Main Selection -> Job State -> All Results. Select the active command event you want to cancel and click Cancel in the menu bar of the All Results view.

When you cancel a command event (in GUI or in CLI) and an abort command is triggered and executed, the results for the command event display state Canceled. In case the original command event is terminated due to some other reason, the results show state Error. For details on command execution check the System Logs.

Setting permissions to run commands

Not every user on a specific client is authorized to run all commands. Without additional entries authorizing selected users to run certain commands, commands can only be run from the system directory <SESAM_ROOT>/bin/sesam. If a command is to be started from another directory before the regular backup is started, this must be entered/allowed on the target client.

UNIX

Copy the file sesam_cmdusers.allow from the directory <SESAM_ROOT>/skel/templates to /etc on the client and modify the file. You can now enter a line for the user and the command in the format {user} {command}. If you use a wildcard (*), all commands will be executed.

No explicit permissions are required to execute SEP sesam commands such as sm_loader.

Windows

To set access rights for the user and command, use the following registry key: 

\\HKLM\SOFTWARE\SEP Elektronik GmbH\sesam\CommandEvents\ <user>\ <command>

In addition, on the client computer, the entry CTRLD_Path=ID/bin/sesam;ID/bin/sms in the file ID/var/ini/sm.ini in the section [CTRLD_Server] must be extended to include the directories in which the desired programs are located.

1. Open the Regedit editor.
2. Go to HKEY_LOCAL_MACHINE\SOFTWARE\SEP Elektronik GmbH\sesam\ and create a new key named CommandEvents. If it does not already exist, right click and select New Key.
3. Enter <user> and then <command> with the full path information as the key.

The available commands are:

Command	Execution
*	all commands
cmd /c	all DOS commands (dir, etc.)
DOS command (e.g., dir)	specific DOS command only (e.g., dir)
specific command (e.g., ping)	specific command only (e.g., ping)

If there are other commands, the last command is executed. If you use a wildcard (*), all commands are executed.

Below is an example of a registry file (*.reg) that allows all command events for the administrator and the sesam user:

Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\SEP Elektronik GmbH\sesam\CommandEvents\sesam\*]
[HKEY_LOCAL_MACHINE\SOFTWARE\SEP Elektronik GmbH\sesam\CommandEvents\Administrator\*]

	Note
	The most common errors when setting up the desired user permissions and allowed commands are: The necessary entries are not entered in the directories of the target clients, are not entered on the server, or are entered incorrectly. Instead of entering a command as a key, it is entered as a string.

See also

Creating Follow-up Events – Creating a Schedule – About Scheduling

Copyright © SEP AG 1999-2023. 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.