Administrators can enable logging of information about files retrieved from the Surround SCM Server. If files are retrieved from the server and returned to a computer running a Surround SCM client, information about who retrieved the files and when is logged to text files in the specified log directory. Information can be logged about all retrieved files or only files with specific extensions.
Logs for retrieved files can be useful for security audits and compliance with National Institute of Standards and Technology (NIST) guidelines. See information about when information may be logged and what is logged. We recommend that you do not log retrieved files unless you have a business reason to because the log files require a large amount of disk space.
1.To log retrieve files, select Log retrieved files.
2. Select which retrieved files to log information about.
- Log all retrieved files logs all files retrieved from the Surround SCM Server to a client computer.
- Only log retrieved files that match the following extensions only logs files that match the specified extensions. Separate multiple extensions with a semicolon.
3. Enter the Log directory path where Surround SCM stores the log files. The default directory is the SCMRetrievedFilesLogs directory in the Surround SCM application directory. Click 
to select a different directory.
The log directory will contain several subdirectories and files. A new subdirectory is created every time the Surround SCM Server starts and when the subdirectory where log files are currently stored reaches the maximum of 30,000 files.
4. Select how many days to Save log files for. The default is 30 days. Valid values are 1 - 999 days.
The Surround SCM Server scans daily for logs that are older than the specified number of days and deletes those files and and any empty log subdirectories. If you need to keep log files longer than the specified number of days, you can back them up. If the value is set to 100 days or more and Log retrieved files is selected or Only log retrieved files that match the following extensions is selected with *.* (Windows) or * (Linux) as the only extension, a warning is displayed that the settings will result in saving a large amount of log data for a long period of time. Consider changing the settings to avoid disk space issues.
When information may be logged
Information is logged when files are retrieved from the server and returned to a computer running a Surround SCM client. Information may be logged when users perform the following actions.
- Add files
- Check in files
- Check out files
- Get files
- View file differences
- View file history
- Perform code reviews
- Shelve and unshelve files
- Search for files using the Find In Files feature
Information logged
The following information is logged about retrieved files.
- Date/time (according to the time zone of the Surround SCM Server)
- Username
- User ID
- Client type
- Client IP — Address for the computer the Surround SCM sends files to. For some Surround SCM clients, this may not be a user's computer. For example, if a user is using the Surround SCM Web, the client IP value is the computer that hosts Surround SCM Web, not the computer the user is accessing Surround SCM from.
- Client hostname — Hostname the Surround SCM client sends to the Surround SCMServer. Users can override and set this value using the Override local computer name user option.
- Mainline name
- Branch name
- Repository path
- Filename
- File version
- Request type — Request that triggered the Surround SCM Server to log information. This is not always the action initiated by the user. The Surround SCM desktop client sometimes sends multiple requests to perform a single action. For example, when undoing a check out with the Get original version option selected, the client performs a get after undoing the check out, so the log will contain Get file as the request type.
- Additional information — Used if there is specific information about a file retrieval that explains where the file came from.
Viewing log files
Log files are stored subdirectories in the directory specified in the Log Retrieved Files settings. A new subdirectory is created each time the Surround SCM Server starts or the subdirectory where logs are currently stored reaches the maximum of 30,000 files. Subdirectories are named incrementally with a number using the following format: retrievedfilelogs_00001.
When using the desktop client, each user session connection creates a new log file. When using the CLI, each command creates a new log file. You can identify log files by Surround SCM username. Files are named using the following format: <usersession_threadid_hex>_<username>_sscmget.log. For example, e2456dce_userjoe_sscmget.log. Usernames are truncated to 25 characters and do not contain any non-file system characters.
Log files are text files in comma-separated (CSV) format. You can view them in any applications that open text files or applications that support CSV format, such as Microsoft Excel.
Because you will likely have a large number of log files, you may need to search across multiple files to find specific information. You can use a third-party utility, such as grep on Unix, to search multiple files for specific phrases or using regular expressions.
Backing up log files
To back up log files, stop the Surround SCM Server and recursively copy the SCMRetrievedFilesLogs directory to another location.
