Environment

Documentation / Professional Edition / User Guide / Appendix / Environment
 

The MyARM agent library can be configured through configuration files(See Appendix Configuration). MyARM needs to find the configuration files during start up. This is achieved by using environment variables under Unix or registry keys under Windows.

Unix setup

Under UNIX the following environment variables can be set to specify the location of the configuration files and to set a valid license key. The easiest way to do this is to use the provided setup.sh script found in the scripts directory of the MyARM installation.

scripts/setup.sh

The setup.sh script is used to setup a MyARM environment in an easy way. The script tests your shell environment and modifies the following system environment variables to enable the full usage of MyARM:

PATH
is modified to add the path to the MyARM programs so that any MyARM program can be executed.
LIBPATH, LD_LIBRARY_PATH
is modified to enable the runtime linker to find MyARM shared libraries (LIBPATH on AIX, LD_LIBRARY_PATH on Linux and Solaris).
MANPATH
is modified to add the MyARM man page directory to the search path of the man system.
MYSQL_UNIX_PORT
is set to the mysql port as used by the current system. If this could not be determined a warning message is issued.
MONO_PATH
is modified if MyARM comes with C# support to add the path for the MyARM assemblies.
PYTHONPATH
is modified if MyARM was installed with ARM 4.0 python support. It adds the directory for the appropriate arm4 python module.

To work properly the following MyARM specific environment variables are set:

MYARM_ROOT
root directory of the MyARM installation.
MYARM_VARRUN_DIR
directory where to store any runtime data such as pid files or temporarily used files
MYARM_VARLOG_DIR
directory where to store any log files
MYARM_VARLIB_DIR
directory where to store any files which need to be persistent such as SQLite databases or MyARM ARM data files
MYARM_CONFIG_URL
contains the configuration end point in URL notation. For more information read section MYARM_CONFIG_URL.
MYARM_LICENSE_KEY
contains the license key of MyARM. This key is extracted from some configuration files. For more information see section "License key".

Usage:

$ . scripts/setup.sh [-q] [config]

The "-q" option suppresses any warning and the basic configuration output. The optional "config" parameter specifies a configuration to be used. This configuration must reside in the MYARM_ROOT/conf or MYARM_ROOT/conf/templates directory.

Typical usage of the setup.sh script, which configures MyARM in the current shell to use the myarmfiled and MySQL database:

user@localhost:/opt/myarm$ . scripts/setup.sh filed_mysql.conf

Windows setup

MyARM for Windows supports registry keys instead of environment variables. During installation of MyARM for Windows the following registry keys are set using the key path, where <var> is a placeholder for the variable names in the following sections (e.g. MYARM_CONFIG_URL). Please note that under Windows no further action is necessary to make these variables known to the MyARM utilities.

MyARM environment variables

MYARM_CONFIG_URL

The MYARM_CONFIG_URL environment variable is used to specify the MyARM configuration file. It uses the common URL notation of the form <protocol>://<host>:<port>/<filepath>. Currently, the following <protocol> types are supported:

file
specifies a local configuration file.
ftp
specifies a ftp remote configuration file (currently not implemented).
http
specifies a http remote configuration file (currently not implemented).

For example, if you want to specify a global <filepath> you have to use two slashes after the protocol indicator, resulting in the following setup:

MYARM_CONFIG_URL=file:////opt/myarm/conf/foo.conf
export MYARM_CONFIG_URL

myarmquery FooTran FooApp

To reference a file within the MYARM_CONFIG_DIR directory, just omit one slash. The following example locates the foo.conf file in the directory configured with the MYARM_CONFIG_DIR environment variable.

MYARM_CONFIG_URL=file:///foo.conf
export MYARM_CONFIG_URL

myarmquery FooTran FooApp

MYARM_CONFIG_DIR

If the MYARM_CONFIG_DIR environment variable is set it contains the absolute path to the directory where all ARM configuration files reside. Therefore you don't need to specify the full path of a configuration file; just use the default file name itself. For example, if you have a configuration stored in the file fooproject.conf which is located in the /usr/local/myarm/conf directory, you can use the following statements:

export MYARM_CONFIG_DIR=/usr/local/myarm/conf

myarmquery -C fooproject.conf FooTran FooApp

MYARM_LICENSE_KEY

If the MYARM_LICENSE_KEY environment variable is set and its not empty it contains the license key to deploy the MyARM components on this host.

MYARM_VARRUN_DIR

This variable is used within the configuration files to reference the directory where to store runtime data like pid files or temporary data.

MYARM_VARLOG_DIR

This variable is used within the configuration files to reference the directory where to log messages.

MYARM_VARLIB_DIR

This variable is used within the configuration files to reference the directory where to store persistent data such as a SQLite database file or ARM data files.

MYARM_TRACE

With the MYARM_TRACE environment variable it is possible to enable diagnostic trace messages during configuration and initialization of the MyARM agent to standard error channel. Currently the following options are supported, which can be combined using a comma character as the delimiter:

none
no tracing at all.
all
enables all the following trace options.
init
enables tracing of initialization and cleanup of the MyARM agent.
env
enables tracing output of all used environment variables.
config
enables tracing output of all configuration properties.
readcfg
enables tracing of reading configuration.

For example:

export MYARM_TRACE=init,env
export MYARM_TRACE=all