The Configuration File

Location and Filename

The default configuration file must be named octoscan.config and must be located in the same directory as Octoscan2.exe.

You can specify alternate configuration files by setting the environment variable OCTOSCAN_CONFIG before calling Octoscan2.exe

Configuration File Format

The configuration file consists of one configuration assignment statement per line. The general syntax is:

<ConfigurationParameter> = <Value>

Comments can be specified by a leading semicolon or hash character.

Boolean parameters can be specified using 1, true or yes for True, 0, false, or no for False. Use double quotes for string values that contain whitespace.

Running Without Configuration File

If you start octoscan2.exe without a configuration file, all parameters are set to their default values. The OutputFolder parameter will be set to ‘.’ (the current working directory). Note that if you start Octoscan2.exe without configuration from a GPO or login script, you have to make sure the current directory is set to the desired output folder.

Sample Configuration File

#
# octoscan2 sample configuration file
#
OutputFolder = \\myserver\OctoSAM$\data
#
# metering (requires metering option)
#
Metering = true
#

Conditions

Simple if / else / end if statements allow for more flexible configuration. The configuration is parsed top down, evaluating the conditional statements.

# scan at every logon
ScanPeriod = 0
# except when logged on remotely through rdp or ica/citrix
# in that case scan only every 10 days.
if remotesession
    ScanPeriod = 240
end if

Conditional statements can be nested:

# scan WMI
ScanHardwareInfo = true
# do not scan WMI when logged on remotely through citrx
if remotesession
    ScanHardwareInfo = false
    # except when the session name starts with ICA-XYZ
    if match string %SESSIONNAME% ICA[-]XYZ.*
         ScanHardwareInfo = true
    end if
end if

The configuration parser is quite simple to keep the size of the scanner executable as tiny as possible. For example there are no logical operators on conditions. You can nest conditional statements but be careful to keep the configuration as straight-forward as possible as nested conditions can be hard to understand.

The same configuration variable can be assigned multiple times. The value at the end of the configuration parse wins.

Environment Variables

You can use references to Windows Environment variables anywhere in the configuration file except for the starting comment character. For example you could provide the Output Folder path in an environment variable and configure

# use enviroment variable %MYGROUP% to build variable folder names
#
OutputFolder = \\myserver\OctoSAM_%MYGROUP%

ProgramFiles Environment Variable

Octoscan2 is a 32bit application to support both 32bit and 64bit Windows installations. When referencing Environment Variables such as %ProgramFiles% in the configuration, be aware that they point to different filesystem locations for 32bit processes.

In addition to this, Octoscan2 unifies process paths for 32-bit and 64-bit and always reports %ProgramFiles% in process signatures. If a program is installed both as 32 and 64bit version on the same machine, only one installation may be reported in some cases.

Configuration Parameters

AlternateScanner

Name	Type	DefaultValue
AlternateScanner	String	"" (empty)

If set, Octoscan will replace itself with the configured alternate scanner. This can be used to run a new version of the scanner only on a subset of machines, or for canary testing together with the canary conditional.

AppendComputerDomainNameToOutputFolder

Name	Type	DefaultValue
AppendComputerDomainNameToOutputFolder	Boolean	false

If true, Octoscan adds the computer’s domain name to the OutputFolderPath. This can be used in a multi-domain environment to get .scan files into different directories per domain. If the directory does not exist on disc, it will be created if possible.

Cleanup

Name	Type	DefaultValue
Cleanup	Boolean	false

If set to true, Octoscan2 will clean up all traces on the system. Use this setting in case you plan to end scanning your environment and want to clean up. You need to leave the invocation logic for Octoscan2 (GPO, Login Scripts etc.) in place for a period long enough to reach most systems.

ImmediateMeteringOutput

Name	Type	DefaultValue
ImmediateMeteringOutput	Boolean	false

If true and Metering also set to true, Octoscan2 will periodically write metering data into a .scax file which can be imported into the database. This is most commonly used in a Terminal Server setting, where sessions are recycled and there is no possibility to persist a metering information file.

ImmediateMeteringOutputFolder

Name	Type	DefaultValue
ImmediateMeteringOutputFolder	String	Value of OutputFolder

Can be used to set a special folder for immediate metering files.

Metering

Name	Type	DefaultValue
Metering	Boolean	false

If true, Octoscan2 will report software usage metering information. Setting this Parameter to true will cause octoscan2 to stay resident during the user session and to periodically scan for programs executed under the current user credentials.

MeteringUseRoamingAppDataFolder

Name	Type	DefaultValue
MeteringUseRoamingAppDataFolder	Boolean	false

If true, Octoscan2 will use the roaming profile to store metering data between invocations. Use this parameter if the local profile gets reset frequently, for example in some terminal server environments.

# use roaming profile on citrix farms
if icasession
   MeteringUseRoamingAppDataFolder=true
end if

OutputFolder

Name	Type	DefaultValue
OutputFolder	String	"." (the current working directory)

Indicates where Octoscan2 should write its output file.

OutputFolder=\\centralserver\OctoSAM$\Data

The last directory in the path will be created if it does not exist and if the parent folder’s permissions allow creation of subdirectories. This is especially useful, if your configuration uses Variables such as:

OutputFolder=\\centralserver\OctoSAM$\Data\%USERDOMAIN%

PushLocal

Name	Type	DefaultValue
PushLocal	Bool	false

If true, Octoscan2 will install itself locally on the scanned computer and will start metering whenever the user logs in.

Scan

Name	Type	DefaultValue
Scan	Bool	true

If set to false, Octoscan2 will not generate a .scan file at all.

ScanSecurityInfo

Name	Type	DefaultValue
ScanSecurityInfo	Bool	false

If true, Octoscan2 will report the security groups the current user belongs to. Currently, OctoSAM Inventory does not use this information and does not import it into the database.

ScanHardwareInfo

Name	Type	DefaultValue
ScanHardwareInfo	Bool	true for workstations true for servers if run with administrator privilege false for servers if run with ordinary user rights

If true, Octoscan2 will report WMI information.

# scan WMI
ScanHardwareInfo = true
# do not scan WMI when logged on remotely through citrx
if remotesession
   ScanHardwareInfo = false
   # except when the session name starts with ICA-XYZ
   if match string %SESSIONNAME% ICA[-]XYZ.*
       ScanHardwareInfo = true
   end if
end if

Some server configuration settings can only be scanned as Administrator. Therefore it’s best to not scan the Hardware & Configuration information if Octoscan2 is not running with Administrator privileges. The setting can be set to true to force Hardware scan on servers for all users, but results might be inconsistent.

ScanProcess

Name	Type	DefaultValue
ScanProcess	Bool	false

If true, Octoscan2 will scan the process table once during scan and report metering data for the processes that are running, even if Metering is turned off. For example, java detection can be improved when java processes are detected on servers even if we do not want software metering. If Metering is turned on anyway, the setting affects only the WMI Scan of Win32_Process.

ScanUalDeviceAccess

Name	Type	DefaultValue
ScanUalDeviceAccess	Bool	true

If true (the default), Octoscan2 will report UAL Device Access statistics on supported systems if the scanner runs with administrator permissions. If set to false, no UAL Device Access statistics logs be scanned. Note that scanning the UAL logs can take quite some time depending on the amount of available data.

ScanUalUserAccess

Name	Type	DefaultValue
ScanUalUserAccess	Bool	true

If true (the default), Octoscan2 will report UAL User Access statistics on supported systems if the scanner runs with administrator permissions. If set to false, no UAL User Access logs will be scanned. Note that scanning the UAL logs can take quite some time depending on the amount of available data.

ScanVisualStudioSetupApi

Name	Type	DefaultValue
ScanVisualStudioSetupApi	Bool	true

If set to the default value of true, Octoscan2 will call into the Microsoft Visual Studio Setup Configuration API to report installed Visual Studio versions and instances. The scan does not add much overhead and almost no overhead if no Visual Studio is detected - so its recommended to keep this scan enabled unless you experience a problem on a specific machine.

Upload Parameters

Octoscan2 supports uploading of generated .scan files to a running OctoCollect upload server on Windows or octopus-resty on Linux. If upload is configured, Octoscan2 will first write the .scan files to a local folder and will try to upload to the specified host(s) later on. If Metering is enabled, Octoscan2 will continue to periodically try to upload the files. Octosoft provides upload server applications for Windows based on NET 5.0 and for Linux based on openresty.

UploadHosts

Name	Type	DefaultValue
UploadHosts	String	"" (empty)

A space separated list of OctoCollect web hosts to where to upload the generated .scan file.

UploadPath (UploadUrl)

Name	Type	DefaultValue
UploadPath	String	"/upload/"

Path on the OctoCollect web hosts to where the upload will be posted.

UploadNoProxy

Name	Type	DefaultValue
UploadNoProxy	Boolean	false

If set to true, the upload ignores any proxy settings. Default is to respect the configured proxy settings for the current user context.

This option is available after Octoscan2 1.10.4.120.

UploadInsecure

Name	Type	DefaultValue
UploadInsecure	Boolean	false

If set to true, Octoscan2 does not test the server certificate. Default is to connect only to a host which presents a valid certificate.

UploadPlainHttp

Name	Type	DefaultValue
UploadPlainHttp	Boolean	false

If set to true, allows upload over plain http. Default is to always use https.

UploadPort

Name	Type	DefaultValue
UploadPort	Integer	443

Port to use on the OctoCollect web host.

Advanced Parameters

These settings should not be used unless advised by Octosoft support.

HardwareScanPeriod

Name	Type	DefaultValue
HardwareScanPeriod	Integer (hours)	0

Specify the minimum time between two hardware and configuration (WMI) scans in hours. If Octoscan2 is restarted within this period of time, no hardware information is scanned to the .scan file produced. Do not use this setting unless advised by Octosoft support. Not scanning at every logon leads to incomplete history information in some inventory data such as IP address history.

OfflineScan

Name	Type	DefaultValue
OfflineScan	Boolean	false

This parameter must be set to true if Octoscan2 is called by the OctoSAM Inventory Offline Scan module (OctoOffline.exe). See OctoSAM Inventory Offline Scan Configuration Guide for more information about offline scans.

ScanDelay

Name	Type	DefaultValue
ScanDelay	Integer (seconds)	0

The initial system scan is delayed for the specified number of seconds after configuration initialization start. This parameter can be used to delay the scan until after logon script is complete and/or software installations have been processed.

Debugging Parameters

AppendMachineNameToScanFileName

Name	Type	DefaultValue
AppendMachineNameToScanFileName	Boolean	false

In some rare cases Octoscan2 may terminate without writing any information to the compressed scan file. This usually indicates a serious problem with the system configuration of affected machines. Adding the machine name to the scan file name may help identify affected systems.

FlushLevel

Name	Type	DefaultValue
FlushLevel	Integer	1

If set to 1, Octoscan2 flushes the collected basic information to the scan file before attempting to perform the software or hardware scan. Setting this parameter to a low value leads to smaller scan files but in case of errors you have potentially less information in the scan file.

FlushLevel	Behavior
0	Produces the smallest .scan files but no information is written if Octoscan2 terminates prematurely
1 (default)	Basic information such machine and user names is flushed to the .scan file as early as possible
2	Flush after each logical block of information
3	Flush after each sub block
4-7	Reserved for debugging
8	Flush on every embedded comment message
9	Flush after every XML element
10	Flush after every line
11	Additional debugging information about the progress of WMI scan

Setting FlushLevel to 0 results in the smallest scan files, but should be used only after you have the scanner running stable with no corrupt scan files for a while.

FlushLevel can also be set through local registry parameters. In that case, the maximum FlushLevel defined will be applied.

Conditional Statements

administrator

True if the scanner runs with Administrator permissions. If UAC is active, this condition is true only if the process actually runs in the elevated administrator mode. If you run the scanner manually from a desktop, you usually need to start it with “Run as Administrator” option.

canary percentage

True if a random generated number between 1 and 100 is lower than the defined percentage. This conditional allows to canary test new settings on a small percentage of scans.

if canary 5
    AlternateScanner=\\server\OctoSAM$\alt_bin\octoscan2.exe
end if

This configuration starts the alternate scanner .exe on approx. 5 percent of all scans.

embedded

True if on an embedded version of Windows.

if embedded
   Metering = false
end if

exists file path

True if the specified file or folder name exists.

if exists file C:\programme\myapp\test.exe
    Metering = false
end if

icasession

True if Octoscan2 is called in a XenDesktop Session

#
# no wmi scan if called through a citrix session login
# in this case we are interested in the Metering data (even if on server).
#
if icasession
    ScanHardwareInfo = false
    Metering = true
    ImmediateMeteringOutput = true
end if

The following example shows an approach to detect Citrix environments:

#
# example to detect citrix environments. 
# note that XenDesktop does not set the remote indicator.
#
if remotesession
    if icasession
        # this is XenApp over ICA
    else
        # standard rdp session (can also be XenApp if RDP is used to connect)
    end if
else
    if icasession
        # this is XenDesktop over ICA
    else
        # this is ordinary desktop
    end if
end if

localsession

True if Octoscan2 is called from the local console. Exact opposite of remotesession.

match machine regex

True if the current machine name (NETBIOS name, lower-case ) matches the specified regular expression.

#
# do not scan if computer name starts with ‘STAFF-‘
#
if match machine staff-.*
    Scan = false
end if

match machinedomain regex

True if the current machine domain name (NETBIOS name, lower-case) matches the specified regular expression.

match user regex

True if the current user name (SAMAccount name, lower-case) matches the specified regular expression.

match upn regex

True if the current UserPrincipalName matches the specified regular expression.

This option is available after Octoscan2 1.10.4.120.

match userdomain regex

True if the current user domain name (NETBIOS name, lower-case) matches the specified regular expression.

match string string regex

True if the supplied string matches (lower-case) the specified regular expression.) This can be used to test values of environment variables for example.

if match string %USERDOMAIN% (devdomain|testdomain)
    Metering = false
end if

minmajor, minminor, minbuild

True if the operating system version is greater or equal the configured value. See MSDN Documentation on OSVERSIONINFOEX for more information.

if minmajor 10
    # meter on windows 10 / Server 2016 only
    Metering = true
end if

remotesession

True if Octoscan2 is called through a remote session, either RDP or ICA.

server

True if on a server operating system

terminalservices

True if terminal services are installed

ualcapable

True if the operating system supports User Access Logging.

workstation

True if on a workstation operating system

wow64

True if Octoscan2 runs on a 64 bit OS.

Message Statement

The message statement allows to send a message to the output window. This can be used to trace complex nested conditions.

if match machine staging-.*
    message "scan disabled for staging machines"
    Scan = false
endif

Java File System Scan

By default Octoscan2 already uses a variety of methods to find installed Java runtimes. For example we inspect the Path, the Java Registry and well known locations for standard installations. However, many software products include their private copy of Java or some users copy a private version of java on their machine without installing.

Octoscan2 allows to scan parts of the filesystem for java executables.

Multiple JavaFileSystemScan commands can be used in a configuration.

Examples

Scan ProgramFiles directories and subdirectories for Java runtimes that come as part from applications

JavaFileSystemScan programfiles

this is equivalent to:

JavaFileSystemScan %ProgramFiles%
if wow64
    # file scan 64-bit programs on 64 bit windows
   JavaFileSystemScan %ProgramW6432%
end if

Scan all local filesystems

JavaFilesystemScan local

Scan the System Drive

JavaFilesystemScan %SystemDrive%\

Scan C: and D: drive if they exist

JavaFileSystemScan C:\
JavaFileSystemScan D:\

Scan all local filesystems on all machines except for fs001 and fs002. Scan only drives c: and d: on these.

if match machine fs001|fs002
    # do not scan large local volumes on these file servers
    JavaFileSystemScan C:\
    JavaFileSystemScan D:\
else
    JavaFileSystemScan local
end if

In complex settings or for special tests you may want to reset already configured scans before you configure new scans

# complex logic here
if ....

end if

# all fine and dandy but for this special machines we want to configure something completely different:

if match machine s0422
    JavaFileSystemScan clear
    JavaFileSystemScan c:/my_special_folder
end if

Custom File Scan

Octoscan2 supports scanning of custom file metadata with the following statement

FileScan <class> <path> 

Multiple FileScan statements can be used in a configuration file together with conditions. The scanned information appears under Hardware % & Configuration (WMI Tables).

Example

FileScan X_CustomConfig "c:/CustomConfig/*.ini"

Since the custom file scan uses the same data structures as WMI (Hardware & Configuration), custom file scan is only done when ScanHardwareInfo is set to true.

Custom File Signature Scan

Octoscan2 supports scanning of custom files metadata, version and digital certificate info with the following statement

FileSignatureScan <path> [recurse] 

Multiple FileSignatureScan statements can be used in a configuration file together with conditions. The scanned information appears as static file: software signature. In case of java .exes an additional java: signature gets generated. This can be useful when a site has a well known installation directory for a site-specific packages that do not conform to the standard installation conventions.

Use file scanning only as a last resort if the package does not leave any other detectable traces on the system. The OctoSAM software catalog does not use file: signatures. These signatures can only be used with custom packages.

The file signature scan is done whenever a software scan is initiated. The user must have read permissions on the files and folders that are to be scanned.

Optional Windows file wildcards are only supported in the filename, the last part of the specified path.

Examples

FileSignatureScan "c:/my application/myprogram.exe"
FileSignatureScan "%ProgramFiles%/my other application/myotherprogram.exe"

Detects site specific executables at a well-known location.

FileSignatureScan c:/mypackages/mypackage/*.exe

Detects all .exe files in the directory c:/mypackages/mypackage

FileSignatureScan c:/mypackages/mypackage/*.dll     recurse

Detects all .dll files in c:/maypackages/maypackage and subdirectories

# file scan 32-bit programs on 32 or 64 bit windows
FileSignatureScan "%ProgramFiles%/*.exe" recurse
# file scan 64-bit programs on 64 bit windows
if wow64
    FileSignatureScan "%ProgramW6432%/*.exe" recurse
end if

Scans all .exe files in the programs folders for 32 and 64 bit Windows.

Custom Registry Scan

Octoscan2 supports inventory of Registry keys with the following statement

RegistryScan <class> <instance> <path> [32|64]

Multiple RegistryScan statements can be used. Class and instance define where a particular scan appears in the Hardware and Configuration tree. The class name should begin with X_ to avoid clashes with future versions of OctoSAM Inventory.

Path can start with HKCU or HKLM for the current user or local machine hives.

The last optional parameter specifies if the 32bit or the 64bit part of the Registry should be scanned. If not set, Octoscan2 will search 32bit first and 64bit only if nothing found in the 32bit part.

Examples

RegistryScan X_IvoSoftClassicShell ClassicShell "HKLM/SOFTWARE/IvoSoft/ClassicShell"
RegistryScan X_AdobeFlash Flash32 "HKLM/SOFTWARE/Adobe/FlashPlayer" 32
RegistryScan X_AdobeFlash Flash64 "HKLM/SOFTWARE/Adobe/FlashPlayer" 64

Resetting Cumulative Scan Configurations

Configuration settings RegistryScan, FileScan, FileSignatureScanand JavaFileSystemScanare cumulative. If multiple statements are encountered while parsing the configuration file, each configured location is added for scanning. Sometimes the configuration logic can be made simpler by resetting already encountered configuration statments. Therefore, these settings support specifying clear as first argument to clear earlier configurations.

For example, you may have some rather complex JavaFileSystemScan configuration and want to change that configuaration for just a couple of specific machines:

if .....
    .... complex logic with multiple JavaFileSignatureScan settings
end if

# special Java scan for thismachine and thatmachine (regardless of prior scan configuration that may also apply)
if match machine thismachine|thatmachine
  JavaFileSystemScan clear
  JavaFileSystemScan c:\
end if

Regular Expressions

To limit the scanner executable size, Octoscan2 supports only a very basic subset of regular expression syntax.

Matching supports only the ASCII character set and is case-insensitive, unless the pattern contains an uppercase character class (\D, \S, \W) - in that case, the match is performed on a lower case version of the value but the regex itself is case sensitive to retain the meaning of these character classes. The match is always performed on the whole string - anchor expressions ^ and $ are implied, whether specified or not. The regex engine supports only greedy, possessive matching.

Syntax	Meaning
.	Matches any character
\b	Matches backspace character (code 0x08)
\f	Matches form feed character (code 0x0C)
\n	Matches new line/line feed character (code 0x0A)
\r	Matches carriage return character (code 0x0D)
\t	Matches horizontal tab character (code 0x09)
\v	Matches vertical tab character (code 0x0B)
\xXX	Matches character 0xXX
\d	Matches any digit character (0-9, codes 0x30-0x39)
\D	Matches any non-digit character
\h	Matches any hexadecimal character (0-9, A-F or a-f)
\H	Matches any non-hexadecimal character
\s	Matches any whitespace character (\f, \n, \r, \t, \v or SPACE)
\S	Matches any non-whitespace character
\w	Matches any word character (0-9, A-Z, a-z or _)
\W	Matches any non-word character
\? * + etc.	Matches meta character
?	Matches zero or one time
*	Matches zero or more times (greedy, possessive)
+	Matches one or more times (greedy, possesssive)
a|b	Matches a or b
()	Capturing group
(?)	Non-capturing group
(?=)	Positive look-ahead
(?!)	Negative look-ahead
^ $	Anchor expressions - implied, the match is always performed as if ^pattern$ had been specified

For further information see subreg github page