> For the complete documentation index, see [llms.txt](https://siff.gitbook.io/siff/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://siff.gitbook.io/siff/guides/service-definition.md). # Service Definition ## Overview A Service Definion (SD) defines a set of config or operational data to me monitiored for a device. A device may have one or many SDs that are applicable. A network device typically will monitor the 'running config' however other sub-systems may also be defined and monitored for changes. A server device for example will likely have multiple SDs that are applicable, SDs that monitor the operating system along with SDs that monitor applications that are deployed on the server. ### SD Discovery During device discovery / validation, a basic set of information is collected that is used to identify the device vendor, model, etc. This information is also use to match against SD Signatures to determine which **active** SDs should be monitoring the device. On network devices, the vendor / model is typically used to determine which SD should be monitored on the device. On servers, the process list is used to determine if an application is running on the server. #### SD Signature The SD Signature can include multiple criteria: * Operating System * Version * Model / Distribution * Architecture * Environment Variables * Config Variables (user-defined configs associated with the device) * Device Tags (user-defined tags associated with the device) * Installed Software * Running Processes * Listening Ports * File Exists * Required Command (command outputs matching)
### Monitored Data Once the **active** SD has been determine that it is applicable to the device, it will start collecting the data and monitor it for changes. There are currently 2 types of data: * Configuration Data * Operational Data ConfigData change infrequently and are kept over a long period of time (yrs) vs OpsData which likely changes at each collection interval and are kept only for 7 days. OpsData only applies the Command resource type and does not include Files and Registry Keys which are ConfigData only. **NOTE**: Please ensure the correct data retention
### Resource Types A **Resource** is the base unit of textual data that is collected and monitored for changes. There are 3 types of Resources: * Commands * Files * Registry Keys (windows agent only) **Command Resource** defines a Resource which consists of a sequence of CLI commands. Only the standard output of the last command is captured as the textual output for the resource. The output of intermediary commands are only used to extract values or arguments that may be used by subsequent commands. An SD will often include multiple Command Resources. Each Resource must have a unique, user-defined Resource Name within the SD. Each Resource are executed sequentially.
**File Resource** defines a Resource which consists of specific files or directory. Directories may specify wildcards in place of filenames as well as globbing for intermediate directories e.g. /etc/httpd/conf/\* of /etc/httpd/\*\*/\*. Each file's absolute path/name represent the resource name.
**Registry Key Resource** defines a Resource which monitor Windows Registry Key(s). It requires the Windows agent to be deployed on the Windows Server. It allows you to specify the Root HKey, Key Path and Key Name (or regex) to be monitored.
## SD Configuration Most out-of-the-box SD content simply work automatically as the devices are discovered. By default, most SD are configured to collect every hourly interval. For older devices, some customers prefer to tune this back to daily intervals. You can also define a set of devices (called Collections group) to override the default interval.
For server and application SDs, some may require configuring the directory or location where the application is deployed. SD configuration parameters are defined in the SD Variables tab.
## SD Community Content The SIFF SD Community is an integrated part of SIFF that includes shared content to help monitor network devices and server / application configs. **Certified** content are automatically available in your environment under the *Monitor > Service Definition > Installed* tab. These certified SDs are *Active* by default and will automatically collect relevant configs on discovery validation. The remaining non-certified SDs must be manually selected and installed i.e. made available in your environment before they can be activated. This is accomplished from the *Monitor > Service Definition > Community* tab. Additionally, certified SDs are automatically updated as new versions become available. Other SD content must manually be selected and updated. This is accomplished from the *Monitor > Service Definition > Updates* tab. Custom SD can be created in your environment. We encourage you to share any commonly applicable or useful SDs with other SIFF users by selecting and sharing the SD from the *Installed* tab. Once shared, they will appear under the *Shared* tab where they will be reviewed as part of the approval process. Approved content will then be visible from the *Community* tab. ## SD Custom Content Development Custom SDs can be created to monitor services or configs that are not currently covered in the SIFF Community Content. When adding a new SD, you will be presented with the following tabs (below). The Registry tab is only visible if the Signature > Platform Operating System is set to *Windows*.
### Description Tab The Description tab is where you define the Name, Description and default settings. Each SD is uniquely identified by its Name#Owner. The SD Alias can be used to relate multiple SDs for easy searching. The *Timeout* field is the max duration of the SD before it is aborted. This includes all the Command Resources, Files and Registry retrieval. The *Interval* field is the duration between each retrieval. Different intervals can be defined for devices that belong to a specified SIFF Collection (i.e. dynamic device groups). See SIFF Collections guide for more details about Collections.
The Sharing options provides some administrative settings for the SD.
### Commands Tab The Commands tab is where you define Resources for CLI commands. The textual output of a CLI command is captured as the content for the user defined named Resource. Each Resource may consists of a sequence of CLI commands and the last command step's output is captured as the content for the Resource. In the example below, the SD contains 2 Command Resources: 'interfaces' and 'port-ipv4-address'. The 'port-ipv4-address' (selected) has 2 command steps: 'term len 0' and 'sh ip int br'. The output from 'sh ip int br' (i.e. 'show ip interface brief') will be captured as the content for the 'port-ipv4-address' Resource. For commands that may prompt for user interaction or response such as confirmation (e.g. y / n), these can be buffered along with the actual command by including a carriage return (e.g. \n) as part of the command. For example, if the 'reboot' command requires a 'y' confirmation, you can specify the command step as: 'reboot\ny'. This would send 'reboot', '\n' and 'y'. For interactive password responses see Command Timeout / Ignore and Interactive Response section below.
#### Command Step Settings The Command Settings, is defined specifically to each command step. **Details Tab** The *Data Retention Type* option is used to determine how long the data is stored. Since the type of data captured for 'sh ip int br' is more operational in nature vs persistent config, you should update the *Data Retention Type* to 'short' to avoid keeping the data long term.
The *Execute On* option is used to indicate where the command is performed, on the target element (e.g. network device) vs on the collector (e.g. linux). This allows command steps to be processed 'locally' on the collector if some complex transformation, lookup, script, etc is required.
The *Sudo / Privileged* option can be used to prefix CLI commands with the sudo / password step before executing the command on linux / unix based systems. Similarly, on netword devices enabling privileged command mode such as the 'enable' CLI command on 'cisco', can be issued before the command step.
The *Command Timeout* option can be used to specify how long to wait for the CLI prompt to appear after the command step is issued. There are 3 type of Command Timeout option: None, Error and Ignore. * None - waits indefinitely for the next CLI prompt to appear or until the overall SD Timeout occurs (see Description tab) * Error - waits for the specified duration and sets the command step as 'fail' if the timeout occurs. Errors can still be handled (see Params / Conditionals below) * Ignore - similar to Error type but does not set the status to 'fail' and just go to the next command step in the sequence after the timeout period. The *Interactive Response* option (requires Command Timeout set to Ignore) forces the command step to skip the CLI prompt detection before the command step is executed. This is particularly useful when handling commands that prompts for a user password input e.g. 'enable'. For password prompts cases, you would set the command step such as 'enable' to Command Timeout Ignore with some short value e.g. 3 seconds, and also set the Interactive Response. This forces the 'enable' command to wait for 3 seconds and then immediately issue the next command step without the CLI prompt detection. The password (which should be a encrypted Variable) would be specified as the next command step.