USER GUIDE Product Snow Inventory Client for Unix Version 1.1.03 Release date 2015-04-29 Document date 2015-05-20
CONTENT ABOUT THIS DOCUMENT... 3 OVERVIEW... 3 OPERATING SYSTEMS SUPPORTED... 3 PREREQUISITES... 3 Dependency on other Snow products... 3 Privileges... 4 EXECUTABLE FILES... 5 HARDWARE AND SOFTWARE INVENTORY... 5 Running processes repository... 6 ORACLE DATABASE PRODUCTS... 6 INSTALLATION... 7 INSTALLATION ON UNIX... 7 JAVA... 7 DEFAULT LOCATION OF FILES... 7 CONFIGURATION... 8 COMMAND LINE PARAMETERS... 8 CONFIGURATION XML FILE... 9 ENCRYPTION OF PASSWORDS... 11 OUTPUT... 11 TRANSPORT OF OUTPUT DATA... 11 USING HTTPS FOR DATA TRANSPORT TO INVENTORY DATA RECEIVER (IDR)... 12 CONFIGURATION IN SEGMENTED NETWORKS... 13 RUNNING THE SNOW INVENTORY CLIENT FOR UNIX... 14 SCHEDULING... 15 KNOWN ISSUES... 15 APPENDIX A... 16 CONFIGURATION EXAMPLES... 16 Example 1: Hardware and software inventory... 16 Example 2: Hardware, software and Oracle inventory... 16 Example 3: Advanced software configuration... 17 Example 4: Send result file to IDR... 18 Page 2 of 18
ABOUT THIS DOCUMENT This document describes how to configure, install, and run the Snow Inventory Client for Unix. OVERVIEW The Snow Inventory Client for Unix is a Java program that is locally installed on the computers that are to be inventoried. The benefit of having a locally installed client on each computer is that inventory can be scheduled to occur on a regular basis always giving up-to-date information on hardware and software changes. The inventory client gathers information about computer hardware and installed software packages from the built-in package manager in Solaris and AIX. Inventory of Oracle database products using the Snow Inventory Oracle Scanner can be enabled as an option. Once the agent is installed on the computer it is recommended to schedule it to run at a given interval. This can be achieved by using the built-in scheduling service in Unix or similar. The Snow Inventory Client for Unix generates an XML file containing the inventory information gathered by the client. The inventory file can be sent to a Snow Inventory Data Receiver (IDR) using http or https. The inventory file needs to be processed by the Snow Integration Manager (formerly known as the Snow External Data Provider) and then imported into the Snow Database using the Snow Inventory Data Processor (IDP). OPERATING SYSTEMS SUPPORTED For information on supported operating systems, see the document System Requirements for all Snow products, which is available for download at www.snowsoftware.com/int/download. PREREQUISITES To run the Snow Inventory Client for Unix, the target computer is required to have Java Runtime Environment 6.0 (1.6) or later installed. NOTE: Due to an internal defect in Java, Java Runtime Environment 1.7.0_7 must not be used. See section Known issues for more information. DEPENDENCY ON OTHER SNOW PRODUCTS The Snow Inventory Client for Unix 1.1.02 requires Snow Integration Manager 4.3 and Snow Inventory Data Provider 4.6 to be installed on the Snow system platform. Page 3 of 18
PRIVILEGES There are two privilege options for running the client, and each option is described in the sections below. Commands like pkginfo, pkgchk must be reachable from the configured path variable in the system. FULL PRIVILEGES A user with privileges to run the Java runtime with the sudo program is required. PRINCIPLE OF LEAST PRIVILEGES A user that has sudo rights to specific operating system commands depending on operating system, see table below. The sudoers file also need to have the NOPASSWD option set. Example from sudoers file: User snow has the rights to execute the commands with sudo and no password: ## ## User privilege specification ## root ALL=(ALL) ALL snow ALL=NOPASSWD: /usr/bin/ls -l /proc/* snow ALL=NOPASSWD: /usr/bin/file Operating system command file ls Description sudo rights needed to get additional file information when performing software inventory Solaris needs this command to read the /proc file system when performing inventory on running processes. If Oracle scan is activated additional permissions need to be granted. An Oracle database user is required for each database that is to be inventoried. The user can be the same for all databases and then configured in the configuration file with the <DefaultInstanceCredentials>. The user can also be unique and configured with the <InstancesWithConfiguration>. Example from sudoers file for Solaris. User snow has the rights to execute the commands with sudo and no password: ## ## User privilege specification ## root ALL=(ALL) ALL snow ALL=NOPASSWD: /usr/bin/pwdx Page 4 of 18
Following commands are used for determining OracleHome. If OracleHome is set in the configuration file, the user doesn t need sudoers rights to this command. Operating system Solaris AIX and Linux HP-UX Command pwdx ls pfiles For more information on Oracle scan, see the User guide for Snow Inventory Oracle Scanner. EXECUTABLE FILES Executable unixclient.jar <config>.xml unixclient.log sios.properties unixclient.properties <resultfile>.xml Description This is the only required file for the Snow Inventory Client for Unix. It is an executable Java archive that performs inventory of hardware, software, and Oracle database products on the current server, on which it is executed. NOTE: The name of the file must not be changed. Configuration file used for advanced configuration of the Snow Inventory Client for Unix (optional). Log file generated when executing unixclient.jar. Properties file containing information about installation date, last run date, Java version, output filename, and version of the Oracle scanner module. Properties file containing information about installation date, last run date, Java version, output filename, and version of the Unix client. The result file from the Snow Inventory Client for Unix. HARDWARE AND SOFTWARE INVENTORY The Snow Inventory Client for Unix will scan the computer and inventory for hardware information relevant for software licensing. The client also performs inventory of software by gathering information from the built-in package manager in AIX and Solaris. Using the Meta information available in the package manager, the client inventories what binary files belongs to what package, and includes this information in the inventory result file. The software scan of packet managers is done by default. There is also a possibility to perform software inventory using scanning of running processes in AIX and Solaris. This can be used as a complement since the package managers don t always have information on all installed software. Information returned from this scan is less descriptive than the information from the package managers. Software inventory using running processes is not performed by default, but has to be enabled in the configuration file. Page 5 of 18
RUNNING PROCESSES REPOSITORY When software inventory is performed and includes running processes, information about these processes and the full path to the files will be stored in a running processes repository. Each time a software scan is initiated a lookup of previously identified running processes is performed to determine if the software is still installed on the client. This will be done even if the process is not currently running at the time of the scan. The result is stored in an encrypted file named tempdata.ser which is placed in the storage path directory. Information on new software will be added to the repository as they are discovered. When a software is removed from the client it will be removed from the repository as well. ORACLE DATABASE PRODUCTS The Snow Inventory Client for Unix can also perform inventory of Oracle database products. Automatic discovery and inventory of all Oracle instances on the computer is easily achieved by the Snow Inventory Oracle Scanner (SIOS), which is integrated in Snow Inventory Client for Unix. To enable Snow Inventory Oracle Scanner, the following configuration option needs to be added to the configuration file of the Snow Inventory Client for Unix: <OracleScan>true</OracleScan> There is also an equivalent for the command line: sudo java jar unixclient.jar sitename=<a SiteName> oraclescan This will trigger the client to run SIOS as part of the inventory process, and automatically perform an inventory of all Oracle database instances found. For information on advanced configuration options for the Oracle database inventory, refer to the User guide for Snow Inventory Oracle Scanner. Page 6 of 18
INSTALLATION INSTALLATION ON UNIX The Java archive can be placed in any directory on the server, but the suggested path is /opt/snow/. The first step of the installation is to create the directory where the.jar file will be placed: $ cd /opt $ mkdir snow Put the file unixclient.jar in the created directory. JAVA If the server has the Java runtime in its path, the client can be run as in the examples in the sections that follow. Otherwise the Java runtime needs to be added to the path, alternatively the Java runtime can be started with the path to the Java installation. Use the commands below to show help and version of the client: $ sudo java -jar unixclient.jar help $ sudo java -jar unixclient.jar version DEFAULT LOCATION OF FILES The table below presents the default locations where the application will put its files if nothing else is configured. The user that started the client must have access to these directories, or the ones specified by configuration. Location /etc/opt/snow /var/opt/snow Description Path where property files will be placed Path where output will be placed (XML and log files) Page 7 of 18
CONFIGURATION The Snow Inventory Client for Unix can be configured using either command line parameters or a configuration XML file (suitable for more complex configurations). COMMAND LINE PARAMETERS The only mandatory parameter is the sitename parameter. All other parameters are optional. Configuration parameters config=<filename> outputpath=<path> sitename=<name> storagepath=<path> oraclescan oracleuser=username oraclepassword=encrypted_password nosoftware nohardware version generateconfig unixshell=<path> posttoidr=<url> runningprocesses help Description Path and name of configuration file. It overrides all options to the left on the command line. Path to where output and log files will be placed. Snow site name i.e MyCorp Path to where properties files will be placed. Oracle scan will be performed. Default user name. Will be used on all logins. Default user password, encrypted with snowcrypt. Software scan will not be performed. Hardware scan will not be performed. Shows version of program. Generates an example configuration file. The example file will be generated in the directory from where the command is run. Path to the shell that should be used by the agent. If not defined the sh shell will be used. URL to IDR where the output file shall be sent. Example: http://idrhost/transferxmlfile.ashx Scans the processes currently running. Shows help information. Page 8 of 18
CONFIGURATION XML FILE Use the following command to generate an example configuration file called ExampleConfig.xml to be saved in the working directory. With this configuration file, a scan of hardware and software can be performed (no Oracle scan). $ sudo java -jar unixclient.jar generateconfig The configuration file is recommended to be placed under /etc/opt/snow. The configuration file is XML based and contains the following tags: Parameter <SiteName> <OutputPath> <StoragePath> <PostResultsToIDR> <IDRAddress> <SoftwareScan> <SoftwareConfig> <RunningProcesses> <ListFileTypes> <ExcludeFileTypes> <Match> <FilterText> <Containing> <FilterText> <EndingWith> <FilterText> <StartingWith> <FilterText> Description Snow Site Name. i.e. MyCorp Path to where output and log files will be placed. Path to where properties files will be placed. true/false. If left out, false. If set as true, the XML file will not be saved locally under OutputPath, even if such tag is specified. http://idrhostadress/transferxmlfile.ashx. https can be used and also port numbers. If https is used, a valid certificate will be needed. Example: https://idrhostadress:9981/transferxmlfile.ashx true/false. If left out, true. Main tag of all Software specific options. Can be left out, for automatic inventory, if left out none of the configuration below applies. true/false. Scan all currently running processes. If left out, false. List all file types found during scanning. File types are listed in the log file. Main tag for software exclusion. Match the following FilterText items. Text to be used with Match. Can be repeated. Exclude files containing the following FilterText item/s. Text to be used with Containing. Can be repeated. Exclude files ending with the following FilterText item/s. Text to be used with EndingWith. Can be repeated. Exclude files starting with the following FilterText item/s. Text to be used with StartingWith. Can be repeated. Page 9 of 18
Oracle Specific configuration settings Parameter <OracleScan> <OracleConfig> <DiscoverAllInstances> <IncludeInstances> <SID> <ExcludeInstances> <SID> <DefaultInstanceCredentials> <User> <Username> <Password> <InstancesWithConfiguration> <Instance> <SID> <User> <Username> <Password> <OracleHome> Description true/false Default = false Main tag of all Oracle specific options. Can be left out, for automatic inventory, if left out none of the configuration below applies. true/false Must be present if OracleConfig is used. Only scan specified instances instead of all instances (DiscoverAllInstances must then be set to false). Can be left out. Database instance SID. Can be repeated. Exclude database instances from being scanned. Can be left out. Database instance SID. Can be repeated. Default credentials to use when log into a database instance if no specific credentials is specified for the specific instance. Can be left out. Tag for specifying Oracle credentials Oracle Username Oracle password, encrypted with snowcrypt. Credentials for specific database instances. Can be left out. Database instance. Can be repeated. Database instance SID Oracle user User name User password Path to the Oracle home for the instance. This value will be used instead of the path found by the automatic discovery. Page 10 of 18
ENCRYPTION OF PASSWORDS Encryption of passwords used in the configuration file and on the command line can be achieved by using a support program called snowcrypt which is available from Snow Support. It is a Windows only program which is run from a command prompt. The program is used in the following way, and the result is displayed on the next line of the command prompt: C:\Snowutils> snowcrypt encryptpass2 MyPassword 145f737f4f357d0ef01ffcc6ee8bd8576ebafcf8e36dfc5ed3c109bae2b24e6f5 OUTPUT Output from Snow Inventory Client for Unix is an XML file containing all inventory information gathered. A log file and a properties file will be created as well. The output files will be placed in /etc/opt/snow if no output path has been specified (either using command line or a configuration file). The result file is generated with a new dynamic filename each time the scanner is run. Example: d424bdfd-0da0-428e-83f7-9b1f0fad6551.xml TRANSPORT OF OUTPUT DATA The XML files generated by the Snow Inventory Client for Unix needs to be processed by Snow Integration Manager (SIM) before import to the Snow Database using the Snow Inventory Data Processor (IDP). The XML result file needs to be transferred to the server running SIM and needs to be placed in the directory defined in the SIM for processing using the Snow Inventory Oracle Scanner plug-in. The built-in functionality of the Snow Inventory Client for Unix can be used to transfer the XML files directly to a Snow Inventory Data Receiver (IDR) installed on the same server running the SIM. Note that the Snow IDR needs to be configured to allow XML file transfers. The recommended method to transfer the XML result file from a Unix server to a Windows server is via the built-in XML transfer to IDR. If this is not possible FTP or SCP can be used to send the file to an FTP/SCP server, configured on the Windows server running the SIM. An alternative would be to use CIFS/SMB to transfer the file to a file share on the Windows server running the SIM, and configure SIM to process Snow Inventory Client for Unix result files from that directory. Page 11 of 18
USING HTTPS FOR DATA TRANSPORT TO INVENTORY DATA RECEIVER (IDR) To use secure data transfer via https, a server certificate needs to be placed in the installation directory of the Snow Inventory Client for Unix. The server certificate needs to be an X.509 public key certificate and have the name *.cer. A Certificate Authority (CA) public key certificate can be used as well. Use the same naming convention as for server. After installation of the certificate, secure data transfer is enabled by changing the IDR address to start with https. See section above on IDR address. An alternative to using server certificates is to tell the Snow Inventory Client for Unix to trust all servers. This is done with the following configuration option: Parameter <IgnoreUnknownCA> Description true/false If set to true, all server certificates will be trusted. If the IDR server needs to validate the client as a known user, client certificates can be used. In that case a key store containing the clients public and private keys is needed. The key store needs to be in the Personal Information Exchange (PFX) format and have the name client.pfx. A blank password must be set for the key store. However, for Java versions older than 7u4 (Java version 7 update 4) the password must be set to Snow123 (without the exclamation marks). The keys contained in the key store need to be without a password. NOTE: There is a limitation in file size when sending files to IIS via https and using Client key certificate. It can be fixed by changing the UploadReadAheadSize on the IIS server. If software scanning is used the files will be rather large and we then recommend not to use client certificates. For more information, see this note about the problem: http://www.microsoft.com/technet/prodtechnol/windowsserver2003/library/iis/7e0d7 4d3-ca01-4d36-8ac7-6b2ca03fd383.mspx?mfr=true Page 12 of 18
CONFIGURATION IN SEGMENTED NETWORKS For complex environments with segmented networks and network connectivity limited by firewalls between network segments, multiple Snow Integration Managers (SIMs) could be setup. Configure one or more SIMs for each network segment to receive and transport the output files from the servers running within the network segment. The SIM servers are then configured to submit their data to the Snow Inventory Data Receiver (IDR) over a permitted port that is configured in the firewall to allow traffic from the SIM Servers to the IDR server. Illustration of segmented network configuration with multiple SIMs: Page 13 of 18
RUNNING THE SNOW INVENTORY CLIENT FOR UNIX Below are some examples of how an inventory can be run. The examples assume that the server has the Java runtime in its path. NOTE: Ideally an inventory agent should be configured not to disturb or consume system resources that are needed for business critical applications running on the server. To achieve this in a Unix environment one would typically use the nice program to set the process priority to low. In the examples that follow niceness is set to 10, but can of course be set to any suitable value. Use the following command line to perform an inventory of hardware and software on the server. The result and log file will be placed in the directory /var/opt/snow. $ sudo java -jar unixclient.jar sitename=mytestsite Use the following command line to perform an inventory of hardware and software on the server. The client will also automatically detect all Oracle instances running on the server and perform inventory of these databases using the user account running the Oracle Instance. The result and log file will be placed in the directory /var/opt/snow. $ sudo java -jar unixclient.jar sitename=mytestsite oraclescan Use the following command line to perform an inventory of hardware and software on the server using a configuration file. The result and log file will be placed in the directory specified by the OutputPath parameter (or in /var/opt/snow if the parameter is not specified). $ sudo java -jar unixclient.jar config=/etc/opt/snow/snowconfig.xml The latter example using nice: $ sudo nice n 10 java -jar unixclient.jar config=/etc/opt/snow/snowconfig.xml Page 14 of 18
SCHEDULING In Unix it is recommended to configure the Snow Inventory Client for Unix to run at a given interval using the scheduler, i.e. CronTab (or similar), to perform inventory, and transfer the XML result file to the Snow Integration Manager (SIM) for processing. In the following example from root Crontab file, the client will run every day at 1:15 in the morning: 15 1 * * * nice -n 10 java -jar /opt/snow/unixclient.jar config=/ opt/snow/configuration.xml For business critical environments Snow Inventory Client for Unix could be scheduled to run within the regular service maintenance windows for the servers. KNOWN ISSUES There is a limitation in file size when sending files to IIS via https and using Client key certificates, see section Using HTTPS for data transport to Inventory Data Receiver (IDR). The Java Runtime Environment (JRE) 1.7.0_07 contains a defect with the consequence that the Oracle inventory does not work. Any server running JRE 1.7.0_07 must upgrade to a later version for the Snow Inventory Oracle Scanner to work properly. There is a validation on the configuration XML file. This means that some items must be in a specific order in the XML file. In case that a failure occurs related to the configuration file, please check the order of the XML tags. Page 15 of 18
APPENDIX A CONFIGURATION EXAMPLES EXAMPLE 1: HARDWARE AND SOFTWARE INVENTORY Hardware and software inventory information will be gathered from the computer, and the result file and log file will be placed in /var/opt/snow. <?xml version="1.0" encoding="utf-8"?> <SnowConfig> <SiteName>MyCorp</SiteName> </SnowConfig> Command line equivalent: sudo java -jar unixclient.jar sitename=mycorp EXAMPLE 2: HARDWARE, SOFTWARE AND ORACLE INVENTORY Hardware and software inventory information will be gathered from the computer. All Oracle instances on the server will be discovered and inventoried. The result file and log file will be placed in /var/opt/snow. <?xml version="1.0" encoding="utf-8"?> <SnowConfig> <SiteName>MyCorp</SiteName> <OracleScan>true</OracleScan> </SnowConfig> Command line equivalent: sudo java -jar unixclient.jar sitename=mycorp oraclescan Page 16 of 18
EXAMPLE 3: ADVANCED SOFTWARE CONFIGURATION The package manager is scanned and all files with an executable flag are filtered according to the content of the configuration file. Files with file information set to match jpeg image info, HTML document and JAVA class file will be filtered. Files with file information containing font file, shell script and ELF 32-bit MSB version 1 shared obj will be filtered. Remaining files from the package manager will be included in the result file. Result and log file will be placed in the sub directory files. <?xml version="1.0" encoding="utf-8"?> <SnowConfig> <SiteName>MyCorp</SiteName> <OutputPath>files</OutputPath> <SoftwareConfig> <ExcludeFileTypes> <Match> <FilterText>jpeg image file</filtertext> <FilterText>HTML document</filtertext> <FilterText>JAVA class file</filtertext> </Match> <Containing> <FilterText>font file</filtertext> <FilterText>shell script</filtertext> <FilterText>ELF 32-bit MSB version 1 shared obj</filtertext> </Containing> </ExcludeFileTypes> </SoftwareConfig> </SnowConfig> Command line equivalent: N/A Page 17 of 18
EXAMPLE 4: SEND RESULT FILE TO IDR The result file will be transferred to the IDR. <?xml version="1.0" encoding="utf-8"?> <SnowConfig> <SiteName>MyCorp</SiteName> <PostResultsToIDR>true</PostResultsToIDR> <IDRAddress>https://idrhostadress:8080/TransferXmlFile.ashx</IDRAddress> </SnowConfig> Command line equivalent: sudo java -jar unixclient.jar sitename=mycorp oraclescan posttoidr=https://idrhostadress:8080/transferxmlfile.ashx Page 18 of 18