Appendix C. Configuration

In order to connect to the RT server, rt needs a few pieces of information. The essential information rt requires is a server to connect to and access information for that server, but several other nonessential variables also are useful to know. Table C-1 lists the available configuration options.

Table C-1. Command-line configuration options

Option	Required	Description
Server name	yes	Specify which RT server to access. This should be a valid hostname. (If you can successfully ping the server using this name, everything should work as expected.)
User	yes	A valid username with access to the server defined.
Password	yes	The appropriate password for the username defined.
Order by	no	How to arrange the results of the query for actions that produce results.
Query string	no	A default query to use when an action requires a query but one isn’t specified.
Debug level	no	A numeric value from 1 to 3 specifying how much rt should log. This is useful for debugging error messages or spurious failures. In normal usage this would not be set and would default to the value 0.
Configuration file	no	Tells rt to use a specific configuration file rather than search for the default .rtrc.
Text editor	no	Sets which editor to use when working from the command line. Defaults to vi if this variable is not set.

You can provide the above information to rt using environment variables or a configuration file, typically .rtrc. The configuration file can’t define the location of the configuration file (for obvious reasons) or the debug level.

Environment Variables

The environment variables unique to rt are all prefixed by RT so as not to interfere with other applications. They are all Uppercase. The following is a list of all the supported variables.

RTUSER

RTPASSWD

RTSERVER

RTDEBUG

RTQUERY

RTORDERBY

RTCONFIG

EDITOR or VISUAL

The following example sets the essential variables in the bash shell:

    $ export RTUSER=rtuser
    $ export RTPASSWD=secret
    $ export RTSERVER=rt.example.com

RTQUERY specifies a default query string:

    $ export RTQUERY="Status='new' and Priority > 7"

With a default query in place, you can call show without any arguments, and it will use the default query:

    $ rt show

You also might change the target server on-the-fly and request a particular ticket instead of using the default query specified in the environment:

    $ RTSERVER=support.example.com rt show ticket/66

Or you might decide to put all this information in a custom configuration file (see Configuration Files later in this chapter). The RTCONFIG environment variable defines which configuration file to use:

    $ export RTCONFIG=/rt/prod/config_file

RTCONFIG is useful when you have multiple different RT servers, perhaps one for internal use and one for external or client use. In this case you might create different configuration files to specify the RT server to access, appropriate user/password combinations and perhaps a default query string and switch between them on the fly:

    $ RTCONFIG=./internal_rtrc rt show
    ...

    $ RTCONFIG=./external_rtrc rt show
    ...

Setting environment variables on your operating system may have limitations or restrictions. See your OS and shell documentation for instructions on the various methods you can use to set them.

Note also that values set in environment variables override values set in the configuration file described below.

Configuration Files

Setting the environment variables for every shell can be troublesome, so rt provides a simpler way: configuration files . These configuration files are simple and consist of a small set of keywords and their values:

    server https://rt.example.com
    user jdoe

The keys for the configuration file are similar to the environment variables, but they don’t have the RT prefix and they’re all lowercase. The configuration file doesn’t have keys equivalent to the RTDEBUG or RTCONFIG environment variables. The available settings are as follows:

server URL

user username

passwd password

query querystring

orderby order

If the environment variable RTCONFIG is not set, rt first looks for a configuration file with the name .rtrc in the current directory. If that file doesn’t exist, rt searches for .rtrc in all parent directories up to the root directory, then in the user’s home directory, and finally looks at /etc/rt.conf. If rt is still missing the required server, user, and password information after searching for configuration files and inspecting the environment variables, it considers it a fatal error and forcibly quits.

The following example is a complete rt configuration file. Note that lines prefixed with the pound # sign are ignored, as are blank lines.

    # This is a sample configuration file
    user      rtuser
    server    http://support.example.com
    passwd    secret
    query     "Status = 'new' and Priority > 5"

At this point, using either the environment variables, the configuration file method, or some combination of both, you should be able to setup rt to access any functional RT server at your disposal.