Advanced usage

This section details the advanced configuration and usage settings for SourceAgent.

Startup script

SourceAgent startup script is aimed to provide easy way to manage SourceAgent server process. Its functionality, though, varies on different platforms.

Linux and Mac OSX

The startup script sa/bin/sa.sh for Linux, Arch Linux ARM and MacOSX takes the following command-line arguments:

  • start - to start server process in the background
  • stop - to stop running server process
  • restart - to stop and start server process in the background
  • status - to check if server process is running
  • configtest - to check if current configuration file syntax is valid. Prints current configuration, list of mount points and enabled API endpoints to stdout and exits.
  • configure - to call first-run configuration wizard. Asks for configuration parameters, saves configuration and exists.
  • enable-boot-start [username] - to launch SourceAgent as a service. You may specify username for an account the service will be launched under, if it differs from current one.
  • disable-boot-start - removes SourceAgent service and stops corresponding process.

For the first five modes, an exit value 0 indicates successful operation, any other value indicates one of the following errors:

1 incorrect script arguments
2 pid file not found, assuming server process is not running
3 server process failed starting
4 server process is dead but pid file exists
5 java executable cannot be found
6 pid file cannot be written
7 server process stopped but pid file cannot be deleted
8 jar cannot be found or is not readable
9 conf file cannot be found or is not readable
10 log dir cannot be found or is not writable
127 error in processing file paths

Last two modes are available only on Linux and Arch Linux ARM. For these, exit code 0 also indicates success, and the meaning of any other value can be figured out by consulting a documentation of the init manager present in the system.

The startup script uses an include script for initializing environment for SourceAgent.

Windows

The service launcher sa\bin\sa.exe takes the following command-line arguments:

  • run [arguments] - to run the SourceAgent program with given arguments without detaching from terminal
  • install [account] - to install the SourceAgent service to be run under specified builtin account or existing managed service account
  • uninstall - to uninstall the SourceAgent service. The service gets stopped first
  • start - to start already installed SourceAgent service
  • status - to get the status of the SourceAgent service
  • stop - to stop running SourceAgent service
  • setup - to install and start the SourceAgent service under virtual account “NT SERVICE\SourceAgent”

Make sure to start the launcher in Command Prompt with elevated privileges for performing service management tasks like install, uninstall, start, stop, setup. The install action adds full control privileges for the specified account to ${SA_HOME} directory.

The service launcher uses an include script for initializing environment for SourceAgent.

Environment Variables

The following environment variables can be set in include script sa/bin/sa.env.sh on Linux, Arch Linux ARM and MacOSX. This script gets invoked by startup script:

  • SA_HOME - specifies absolute path to SourceAgent installation directory (sa/). The system user account launching SourceAgent server must have read and write permissions in this directory. If it is not set explicitly, the startup script sets it to a value of absolute path of a parent of its parent directory. If this variable is set, the “-c” command-line option becomes optional, as configuration file path is assumed to be $SA_HOME/conf/sa.conf in this case.

  • JAVA_HOME - specifies path to JRE/JDK 1.8 home directory. If not set the packaged JRE is used (from the sa/jre/ directory).

  • JAVA_OPTS - specifies list of values for named system properties for the SourceAgent Java process, each of the form -D<name>=<value>.

  • SA_LAUNCHER_ARGS - command line arguments for the SourceAgent server java process invoked by startup script. You may add -v[v[v]] to increase logging verbosity level.

  • SA_STD_LOG_DIR - specifies absolute path to a directory for stdout and stderr log files produced by startup script on Linux, Arch Linux ARM and Mac OSX.

System properties

There are no mandatory system properties. The following system properties are set by default in system properties file sa\bin\sa.exe.vmoptions used by service launcher on Windows:

  • SA_HOME - specifies absolute path to SourceAgent installation directory (sa/). The system user account launching SourceAgent server must have read and write permissions in this directory. If it is not set explicitly, the launcher sets it to a value of absolute path of a parent of its parent directory. If this variable is set, the “-c” command-line option (only used in “run” mode) becomes optional, as configuration file path is assumed to be SA_HOMEconfsa.conf in this case.

  • SA_LOG_DIR - the value of this property is used in default configuration file for specifying log directory.

The properties must be specified in the file in the form -D<name>=<value>, one on each line. The lines starting with # are treated as comment lines.

Misc System Properties

The following system properties are possible to specify for the server’s java process:

  • com.spectx.zlib.path - path to zlib library/dll. The server bundle comes with prebuilt zlib native libraries for OSX, Windows and Linux platforms. Should you need to use different zlib library version you can use this property to specify fully-qualified pathname of it’s location using as a value for variable JAVA_OPTS in environment variables definition file as follows:

    JAVA_OPTS="${JAVA_OPTS} -Dcom.spectx.zlib.path=/path/to/zlib.so"