Agent configuration file

The agent configuration file is an XML file named snowagent.config. It contains configurable settings telling the Snow Inventory Agents for Windows, macOS, Linux, and Unix what to inventory, when to inventory, and where to send the inventory result. The file must be included in the agent installation package. The default location after installation is in the agent installation directory.

Each element of the file contains settings related to a specific area. This page gives an overview of each element. For a complete specification of all elements and settings, see Configuration reference.

Agent

For a complete specification of the contents of the element, see Agent.

The Agent element contains two tags: SiteName and ConfigName.

EXAMPLE

<Agent>
    <SiteName>StockholmOffice-Finance</SiteName>
    <ConfigName>LinuxServer-Oracle</ConfigName>
</Agent>

Use SiteName to specify a location or department.

Use ConfigName to identify a unique agent configuration. You will probably need to create more than just one agent package depending on the type of computer the agent will be installed on.

As a Snow Atlas customer, these two tags mainly act as labels that can help you group computers in SAM Core, as these tags are available in many of the reports.

As a Snow License Manager customer, these values serve a more direct purpose, as you can manage and update your agents from the Snow Inventory Admin Console based on the agent's site name and configuration name.

Schedule

For a complete specification of the contents of the element, see Schedule.

The Schedule element is only applicable to the Windows agent. It tells the agent when to perform the scan routine. For the other agents, the scan schedule is configured outside of the configuration file.

The element is required for the agent to perform automatic scans. The element can be omitted, for example, for troubleshooting purposes or when zero-footprint inventory is used.

EXAMPLE

<Schedule>
    <Task>
        <Action>scan</Action>
        <Occurance>
            <AtStart>true</AtStart>
            <Daily>true</Daily>
        </Occurance>
        <TimeOfDay>09:00</TimeOfDay>
        <Randomize>60</Randomize>
    </Task>
</Schedule>

Use the Occurance element to configure the agent to run the scan either daily, weekly, or monthly. If you want the agent to perform a scan every time the agent service is started, set AtStart to true.

You can specify the time of day for when the daily, weekly, or monthly scan will start in TimeOfDay.

To make sure that not all agents scan and send their results at the same time, with the risk of choking the endpoint with too many simultaneous files, you can specify a randomization interval in minutes in Randomize. A random number of minutes within the specified interval will then be added to the time specified in TimeOfDay. In the example above, the agent will scan and send the data sometime between 9 and 10 in the morning.

Meter

For a complete specification of the contents of the element, see Meter.

The Meter element is only applicable to the Windows agent. You can use it to configure the rules for desktop application metering, such as when the metering should occur and any desktop applications that should be excluded from metering. See Metering of desktop application usage for more information on the desktop application metering function for the Windows agent.

EXAMPLE

<Meter>
    <Exclude>
        <Path>%windir%\*</Path>
    </Exclude>
    <Span>
        <StartTime>PT00H00M</StartTime>
        <EndTime>PT23H59M</EndTime>
    </Span>
    <Occurance>
        <Weekday>monday</Weekday>
        <Weekday>tuesday</Weekday>
        <Weekday>wednesday</Weekday>
        <Weekday>thursday</Weekday>
        <Weekday>friday</Weekday>
        <Weekday>saturday</Weekday>
        <Weekday>sunday</Weekday>
    </Occurance>
</Meter>

Specify paths for any software you want to exclude from metering in Exclude. You can use '*' as a wildcard. For example, <Path>C:\Windows\*</Path> will exclude all software that is run from the C:\Windows directory.

Specify the start and end time of day for the metering in Span.

Specify one or more days of the week on which you want the metering to occur in Occurance.

Software

For a complete specification of the contents of the element, see Software.

The contents of the Software element determine what parts of the file system the agent will include in the scan.

EXAMPLE

<Software>
    <Include>
        <Path recursive="true">C:\ProgramData\*</Path>
    </Include>
    <Exclude>
        <Path>%windir%\*</Path>
    </Exclude>
</Software>

The agent will scan locations specified in the Include element, while locations specified in the Exclude element will be excluded from the scan. Additional elements and attributes can be used to further refine the scope of the scan.

Configuration examples

While the detailed specifications can be found in Software, the examples in this section aim at clarifying the usage and behavior of some components of the Software element for Windows, macOS, and Linux. The examples are gathered in the following sections:

• Basic include path configuration
• Scan include paths recursively
• Basic exclude path configuration
• Wildcards
• Exclude expressions
• Override default file exclusion

Basic include path configuration

Include paths, that is, paths specified in the Include element, determine from where files are collected during a scan.

EXAMPLE

This example demonstrates how to include all files within a specific directory using different configuration variants.

Folder structure:

/root
├── file-1.py
├── /folder-a
│   ├── file-2.py
│   └── /subdir
│       └── file-3.txt
└── /folder-b
    ├── file-4.py
    └── /subdir
        └── file-5.txt

Configuration:

All three configurations below are equivalent.

Configuration 1:

<Software>
    <Include><Path>/root/folder-a</Path></Include>
</Software>

Configuration 2:

<Software>
    <Include><Path>/root/folder-a/</Path></Include>
</Software>

Configuration 3:

<Software>
    <Include><Path>/root/folder-a/*</Path></Include>
</Software>

Result:

/root
└── /folder-a
    └── file-2.py

note

If the leaf of a path does not contain a wildcard, it will be interpreted as a folder. For example, both of the following paths will treat folder-a as a folder:

<Path>/root/folder-a</Path>
<Path>/root/folder-a/</Path>

When an include folder is specified, the default behavior is to analyze all files within that folder. Therefore, these two paths are equivalent to:

<Path>/root/folder-a/*</Path>

The wildcard * explicitly indicates that all files within folder-a are analyzed.

Scan include paths recursively

Setting the recursive attribute in the Include element to true tells the agent to scan subdirectories of the specified include paths. This ensures that all files within the specified folder and its subdirectories are included in the scan.

EXAMPLE

This example demonstrates how to include all files within a folder and its subdirectories by enabling the recursive attribute.

Folder structure:

/root
├── file-1.py
├── /folder-a
│   ├── file-2.py
│   └── /subdir
│       └── file-3.txt
└── /folder-b
    ├── file-4.py
    └── /subdir
        └── file-5.txt

Configuration:

The following configuration includes all files recursively under folder-a:

<Software>
    <Include><Path recursive="true">/root/folder-a/</Path></Include>
</Software>

Result:

/root
└── /folder-a
    ├── file-2.py
    └── /subdir
        └── file-3.txt

note

By default, include paths are not recursive. Setting the recursive attribute to true explicitly enables scanning of subdirectories.

Basic exclude path configuration

Exclude paths, that is, paths specified in the Exclude element, define locations that will be excluded from the scan.

EXAMPLE

Folder structure:

/root
├── file-1.py
├── /folder-a
│   ├── file-2.py
│   └── /subdir
│       └── file-3.txt
└── /folder-b
    ├── file-4.py
    └── /subdir
        └── file-5.txt

Configuration:

Include all files from /root recursively, while excluding everything in folder-b.

<Software>
    <Include><Path recursive="true">/root/*</Path></Include>
    <Exclude><Path>/root/folder-b/*</Path></Exclude>
</Software>

Result:

/root
├── file-1.py
└── /folder-a
    ├── file-2.py
    └── /subdir
        └── file-3.txt

note

Exclude paths are always recursive.

Wildcards

The wildcard * can be used for matching a sequence of characters in include and exclude paths. It can match both files and folders. When enclosed between two /, for example, /root/*/, the wildcard matches folders, whereas when placed after the last /, for example, /root/*, it matches files.

EXAMPLE

Using wildcards to match folders.

Folder structure:

/root
├── file-1.py
├── /folder-a
│   ├── file-2.py
│   └── /subdir
│       └── file-3.txt
└── /folder-b
    ├── file-4.py
    └── /subdir
        └── file-5.txt

Configuration:

Require the leaf folder to be named subdir, while permitting any folder names in the path above it, as long as they are under /root.

<Software>
    <Include><Path>/root/*/subdir/*</Path></Include>
</Software>

Result:

/root
├── /folder-a
│   └── /subdir
│       └── file-3.txt
└── /folder-b
    └── /subdir
        └── file-5.txt

EXAMPLE

Using wildcards to match files.

Folder structure:

/root
├── file-1.py
├── /folder-a
│   ├── file-2.py
│   └── /subdir
│       └── file-3.txt
└── /folder-b
    ├── file-4.py
    └── /subdir
        └── file-5.txt

Configuration:

Recursively include all files and directories under /root, but exclude any files with a .txt extension at any level.

<Software>
    <Include><Path recursive="true">/root/*</Path></Include>
    <Exclude><Path>/root/*.txt</Path></Exclude>
</Software>

Result:

/root
├── file-1.py
├── /folder-a
│   └── file-2.py
└── /folder-b
    └── file-4.py

Exclude expressions

Exclude expressions (using the exp: prefix) allow you to simplify the exclusion of specific files or directories based on patterns, regardless of their location in the folder structure. These expressions use flexible wildcard patterns to dynamically match paths, making it easier to exclude multiple files or directories without explicitly specifying each one.

If you omit all include directives and use the default settings to scan all local drives on Windows, or use an include path of /* on Linux or macOS, while relying solely on pattern matching to exclude specific folders, you will experience a performance decrease compared to using a set of more specific include paths. This is because, without more specified include paths, the scan will search for exclude patterns across the entire file system, which is time-consuming.

EXAMPLE

Exclude a specific directory by name.

Folder structure:

/root
├── file-1.py
├── /folder-a
│   ├── file-2.py
│   └── /subdir
│       └── file-3.txt
└── /folder-b
    ├── file-4.py
    └── /subdir
        └── file-5.txt

Configuration:

Include all files recursively under /root, but exclude any files located in directories named subdir, regardless of their location in the folder structure.

<Software>
    <Include><Path recursive="true">/root/*</Path></Include>
    <Exclude><Path>exp:*/subdir</Path></Exclude>
</Software>

Result:

/root
├── file-1.py
├── /folder-a
│   └── file-2.py
└── /folder-b
    └── file-4.py

note

For expressions (exp:), there is a performance benefit to omitting either / or /* at the end of the expression. This omission will cause subdir to be interpreted as a directory that will be excluded from the scan. For example, using exp:*/subdir/ or exp:*/subdir/* would cause all files in subdir to be traversed, even though they would still be excluded. Note the difference compared to normal include and exclude paths, where there is no difference in behavior for path endings such as /root, /root/, or root/*.

EXAMPLE

Exclude Python files in directories starting with folder-.

Folder structure:

/root
├── file-1.py
├── /folder-a
│   ├── file-2.py
│   └── /subdir
│       └── file-3.txt
└── /folder-b
    ├── file-4.py
    └── /subdir
        └── file-5.txt

Configuration:

Include all files recursively under /root, but exclude Python files (*.py) located in directories whose names start with folder-.

<Software>
    <Include><Path recursive="true">/root/*</Path></Include>
    <Exclude><Path>exp:*/folder-*/*.py</Path></Exclude>
</Software>

Result:

/root
├── file-1.py
├── /folder-a
│   └── /subdir
│       └── file-3.txt
└── /folder-b
    └── /subdir
        └── file-5.txt

Override default file exclusion

For Linux and macOS, files without the executable bit set are excluded from file scanning results by default. To override this behavior for the specified path, use the unconditionally attribute in the Include element. Setting this attribute to true will include all files within the specified path, even those without the executable bit set.

Note that the unconditionally attribute has a different function on Unix, see Include.

EXAMPLE

Remove parts of the executable bit filtering (Linux and macOS).

Folder structure:

/root
├── file-1.py
├── /folder-a
│   ├── file-2.py
│   └── /subdir
│       └── file-3.txt
└── /folder-b
    ├── file-4.py
    └── /subdir
        └── file-5.txt

Configuration:

Include all Python files under root but only include text files from folder-a/subdir. For this example, assume that all Python files have the executable bit set and text files do not.

<Software>
    <Include><Path recursive="true">/root/*</Path></Include>
    <Include><Path unconditionally="true">/root/folder-a/subdir/*</Path></Include>
</Software>

Result:

/root
├── file-1.py
├── /folder-a
│   ├── file-2.py
│   └── /subdir
│       └── file-3.txt
└── /folder-b
    └── file-4.py

Since the unconditionally attribute is only set for /root/folder-a/subdir/*, all other text files will be filtered out because they do not have the executable bit set.

Registry

For a complete specification of the contents of the element, see Registry.

The Registry element is only applicable to the Windows agent. You can use it if you want the agent to include additional information from the Windows Registry in the scan result.

EXAMPLE

<Registry>
  <Query>
     <Key>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT</Key>
     <Value>Version</Value>
  </Query>
</Registry>

Logging

For a complete specification of the contents of the element, see Logging.

The Logging element tells the agent what to log and how large the log files are allowed to become before a new file is created and older log files are deleted.

EXAMPLE

<Logging>
    <MaxSize>1024</MaxSize>
    <!-- error, warning, info, trace, verbose -->
    <Level>error</Level>
</Logging>

The max size is specified in kilobytes.

Log levels range from error, where only error messages are logged, to verbose, where the agent is writing more or less everything it does throughout the day. verbose can be used when troubleshooting an agent installation. Each log level includes the preceding log level, for example, info includes warning and error.

Server

For a complete specification of the contents of the element, see Server.

The Server element tells the agent which endpoints to send the .snowpack files to.

EXAMPLE

<Server>
    <Endpoint>
        <Address>https://endpointserver:8080</Address>
        <Proxy>
            <Server>http://proxyserver:80</Server>
        </Proxy>
        <ClientCertificate>
            <FileName>name</FileName>
            <Password>pwd</Password>
        </ClientCertificate>
    </Endpoint>
</Server>

<Endpoint><Address> is the only mandatory tag. It should hold the URL to either a Snow Extender, a Service Gateway, or a Master Server, depending on the server technology you have installed. You can specify several endpoint addresses by adding several Endpoint elements. In that case, the agent will randomly select an address and attempt to make a connection. As soon as it has successfully managed to negotiate a connection it will use that one for the remainder of the session. Note that the more server endpoints defined in the agent configuration, the longer it will take to negotiate a connection. This is typically not an issue but when writing scripts, keep in mind that it may introduce a significant delay since the agent has to timeout on a bad server endpoint configuration before it can try the next one.

You can also add information about proxy servers and client certificates.

DropLocation

For a complete specification of the contents of the element, see DropLocation.

Use the DropLocation element if you want to send a copy of each created .snowpack file to an additional location. The location can be a network folder, an HTTP endpoint, or a UNC file path. If more than one drop location is configured, all drop locations will receive a copy.

EXAMPLE

<DropLocation>
    <Path>c:\temp\SnowPackOutput</Path>
</DropLocation>

Note that if the agent cannot reach a drop location during the send activity, it will not try to resend the file later.

Oracle

For a complete specification of the contents of the element, see Oracle.

The Oracle element is used together with the Snow Inventory Oracle scanner, an optional script that will log in to a locally installed Oracle database and retrieve information about the database users, management packs, and options. The scanner can be included in the agents for Linux, Unix, and Windows.

EXAMPLE

<Oracle enabled="true">
    <Include>
        <AllInstances>true</AllInstances>
    </Include>
</Oracle>

When the enabled setting is set to true, the agent will run the Snow Inventory Oracle scanner as part of the scanning process, and automatically perform an inventory of all Oracle database instances found.

Include specifies which database instances should be scanned. It is preconfigured to scan all instances.

SystemSettings

The SystemSettings element contains various settings changing the behavior of the agent in different ways. More than 70 settings can be added to the element. For a complete specification of all settings, see SystemSettings.

Some examples:

env.is_virtual_desktop_infrastructure: If you install agents in a VDI environment, you will need to include this setting for the computers to be inventoried as VDI devices, which is important to license your VDI environment correctly.

env.java_home: If you are running the Snow Inventory Oracle scanner to inventory your Oracle databases, you might need this system setting to locate the Java installation path. As the Oracle scanner is a Java application, it needs access to a Java runtime. Sometimes the Java runtime path is added to the system variables, and in those cases, this path can be omitted from the agent configuration file. But in cases when the Java path is unknown to the system, you can specify it here.

Cloud application metering settings

The saas.[browser].enabled and saas.all_managed settings are described in this section.

The saas.[browser].enabled settings, for example saas.firefox.enabled, are used to enable or disable the cloud application metering feature on the agent side for the respective browser. The settings can have the following values:

• false - disables the cloud application metering feature on the agent side.

• true - enables the cloud application metering feature on the agent side.

• enable - enables the cloud application metering feature on the agent side and prevents the agent from installing or uninstalling the browser extension. The browser extension must instead be installed outside the agent, for example via a management tool.

The tables below show how the agents handle the extensions depending on the configuration of the saas.[browser].enabled settings.

Snow Inventory Agent for Windows:

	At agent startup	At agent shutdown
false	Complete uninstall	Complete uninstall
enable	Enable extension, but do not install it	Disable extension, but do not uninstall it
true	Enable/install extension	Complete uninstall

Snow Inventory Agent for macOS:

	Webmetering rules files present in agent installation folder	No webmetering rules files in agent installation folder
false	Complete uninstall	Complete uninstall
enable	Write nativehost and manifest	Remove nativehost and manifest
true	Install extension and write nativehost and manifest	Complete uninstall

The saas.all_managed setting is used to run the cloud application metering feature in managed mode. If set to true, the agent is enabled to collect cloud application metering data, but will not perform any installations related to cloud application metering. The setting overrides the saas.[browser].enabled settings.

For a complete description of the cloud application metering solution, see Cloud application metering. For a description on how to use the cloud application metering settings listed in this section, see Manage browser extensions.

Environment

For a complete specification of the contents of the element, see Environment.

Use the Environment element to specify any variables the agent should not gather from the environment.

EXAMPLE

<Environment>
  <Ignore>USERNAME</Ignore>
</Environment>

SudoCommands

For a complete specification of the contents of the element, see SudoCommands.

Use the SudoCommands element if you want to enable the Unix agent to run a complete scan without being run as a super-user, see Run the agent according to the principle of least privileges.

The element is only applicable to the Unix agent.

EXAMPLE

<SudoCommands>
  <Path>/usr/bin/file</Path>
  <Path>/usr/bin/ls</Path>
</SudoCommands>