
\section{Global (Site, User) Config File Reference}
\label{SiteRCReference}

\lstset{language=transcript}

This section defines all legal items and values for cylc site and
user config files. See {\em Site And User Config Files}
(Section~\ref{SiteAndUserConfiguration}) for file locations, intended
usage, and how to generate the files using the
\lstinline=cylc get-site-config= command.

{\em As for suite definitions, Jinja2 expressions can be embedded in
site and user config files to generate the final result parsed by cylc.}
Use of Jinja2 in suite definitions is documented in
Section~\ref{Jinja2}.

\subsection{Top Level Items}

\subsubsection{temporary directory}

A temporary directory is needed by a few cylc commands, and is cleaned
automatically on exit. Leave unset for the default (usually
\lstinline=$TMPDIR=).

\begin{myitemize}
\item {\em type:} string (directory path)
\item {\em default:} (none)
\item {\em example:} \lstinline@temporary directory = /tmp/$USER/cylc@
\end{myitemize}

\subsubsection{process pool size}

Number of process pool worker processes used to execute shell commands
(job submission, event handlers, job poll and kill commands).

\begin{myitemize}
\item {\em type:} integer
\item {\em default:} None (number of processor cores on the suite host)
\end{myitemize}

\subsubsection{disable interactive command prompts}

Commands that intervene in running suites can be made to ask for
confirmation before acting. Some find this annoying and ineffective as a
safety measure, however, so command prompts are disabled by default.

\begin{myitemize}
\item {\em type:} boolean
\item {\em default:} True
\end{myitemize}

\subsubsection{enable run directory housekeeping}

The suite run directory tree is created anew with every suite start
(not restart) but output from the most recent previous runs can be
retained in a rolling archive. Set length to 0 to keep no backups.
{\bf This is incompatible with current Rose suite housekeeping} (see
Section~\ref{SuiteStorageEtc} for more on Rose) so it is disabled by
default, in which case new suite run files will overwrite existing ones
in the same run directory tree. Rarely, this can result in incorrect
polling results due to the presence of old task status files.

\begin{myitemize}
\item {\em type:} boolean
\item {\em default:} False
\end{myitemize}

\subsubsection{run directory rolling archive length}

The number of old run directory trees to retain if run directory
housekeeping is enabled.
\begin{myitemize}
\item {\em type:} integer
\item {\em default:} 2
\end{myitemize}

\subsubsection{execution polling intervals}
\label{execution_polling}

Cylc can poll running jobs to catch problems that prevent task messages
from being sent back to the suite, such as hard job kills, network
outages, or unplanned task host shutdown. Routine polling is done only
for the polling {\em task communication method} (below) unless
suite-specific polling is configured in the suite definition.
A list of interval values can be specified, with the last value used
repeatedly until the task is finished - this allows more frequent
polling near the beginning and end of the anticipated task run time.
Multipliers can be used as shorthand as in the example below.

\begin{myitemize}
\item {\em type:} ISO 8601 duration/interval representation (e.g.
\lstinline=PT10S=, 10 seconds, or \lstinline=PT1M=, 1 minute).
\item {\em default:}
\item {\em example:} \lstinline@execution polling intervals = 5*PT1M, 10*PT5M, 5*PT1M@
\end{myitemize}


\subsubsection{submission polling intervals}
\label{submission_polling}

Cylc can also poll submitted jobs to catch problems that prevent the
submitted job from executing at all, such as deletion from an external
batch scheduler queue. Routine polling is done only for the polling {\em
task communication method} (below) unless suite-specific polling
is configured in the suite definition. A list of interval
values can be specified as for execution polling (above) but a single
value is probably sufficient for job submission polling.

\begin{myitemize}
\item {\em type:} ISO 8601 duration/interval representation (e.g.
\lstinline=PT10S=, 10 seconds, or \lstinline=PT1M=, 1 minute).
\item {\em default:}
\item {\em example:} (see the execution polling example above)
\end{myitemize}

\subsubsection{task host select command timeout}

When a task host in a suite is a shell command string, cylc calls the shell to
determine the task host. This call is invoked by the main process, and may
cause the suite to hang while waiting for the command to finish. This setting
sets a timeout for such a command to ensure that the suite can continue.

\begin{myitemize}
\item {\em type:} ISO 8601 duration/interval representation (e.g.
\lstinline=PT10S=, 10 seconds, or \lstinline=PT1M=, 1 minute).
\item {\em default: PT10S}
\end{myitemize}

\subsection{[task messaging]}

This section contains configuration items that affect task-to-suite
communications.

\subsubsection[retry interval]{[task messaging] \textrightarrow retry interval}

If a send fails, the messaging code will retry after a configured
delay interval.

\begin{myitemize}
\item {\em type:} ISO 8601 duration/interval representation (e.g.
\lstinline=PT10S=, 10 seconds, or \lstinline=PT1M=, 1 minute).
\item {\em default:} PT5S
\end{myitemize}

\subsubsection[maximum number of tries]{[task messaging] \textrightarrow maximum number of tries}

If successive sends fail, the messaging code will give up after a
configured number of tries.

\begin{myitemize}
\item {\em type:} integer
\item {\em minimum:} 1
\item {\em default:} 7
\end{myitemize}

\subsubsection[connection timeout]{[task messaging] \textrightarrow connection timeout}

This is the same as the \lstinline=--pyro-timeout= option in cylc
commands. Without a timeout Pyro connections to unresponsive
suites can hang indefinitely (suites suspended with Ctrl-Z for instance).

\begin{myitemize}
\item {\em type:} ISO 8601 duration/interval representation (e.g.
\lstinline=PT10S=, 10 seconds, or \lstinline=PT1M=, 1 minute).
\item {\em default:} PT30S
\end{myitemize}

\subsection{[suite logging]}

The suite event log, held under the suite run directory, is maintained
as a rolling archive. Logs are rolled over (backed up and started anew)
when they reach a configurable limit size.

\subsubsection[roll over at start-up]{[suite logging] \textrightarrow roll over at start-up}

If True, a new suite log will be started for a new suite run.

\begin{myitemize}
\item {\em type:} boolean
\item {\em default:} True
\end{myitemize}

\subsubsection[rolling archive length]{[suite logging] \textrightarrow rolling archive length}

How many rolled logs to retain in the archive.

\begin{myitemize}
\item {\em type:} integer
\item {\em minimum:} 1
\item {\em default:} 5
\end{myitemize}

\subsubsection[maximum size in bytes]{[suite logging] \textrightarrow maximum size in bytes}

Suite event logs are rolled over when they reach this file size.

\begin{myitemize}
\item {\em type:} integer
\item {\em default:} 1000000
\end{myitemize}

\subsection{[documentation]}

Documentation locations for the \lstinline=cylc doc= command and gcylc
Help menus.

\subsubsection[{[[}files{]]}]{[documentation] \textrightarrow [[files]]}

File locations of documentation held locally on the cylc host server.

\paragraph[html index]{[documentation] \textrightarrow [[files]] \textrightarrow html index }

File location of the main cylc documentation index.
\begin{myitemize}
\item {\em type:} string
\item {\em default:} \lstinline=$CYLC_DIR/doc/index.html=
\end{myitemize}

\paragraph[pdf user guide]{[documentation] \textrightarrow [[files]] \textrightarrow pdf user guide }

File location of the cylc User Guide, PDF version.
\begin{myitemize}
\item {\em type:} string
\item {\em default:} \lstinline=$CYLC_DIR/doc/cug-pdf.pdf=
\end{myitemize}

\paragraph[multi-page html user guide]{[documentation] \textrightarrow [[files]] \textrightarrow multi-page html user guide }

File location of the cylc User Guide, multi-page HTML version.
\begin{myitemize}
\item {\em type:} string
\item {\em default:} \lstinline=$CYLC_DIR/doc/html/multi/cug-html.html=
\end{myitemize}

\paragraph[single-page html user guide]{[documentation] \textrightarrow [[files]] \textrightarrow single-page html user guide }

File location of the cylc User Guide, single-page HTML version.
\begin{myitemize}
\item {\em type:} string
\item {\em default:} \lstinline=$CYLC_DIR/doc/html/single/cug-html.html=
\end{myitemize}

\subsubsection[{[[}urls{]]}]{[documentation] \textrightarrow [[urls]]}

Online documentation URLs.

\paragraph[internet homepage]{[documentation] \textrightarrow [[urls]] \textrightarrow internet homepage }

URL of the cylc internet homepage, with links to documentation for the
latest official release.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} http://cylc.github.com/cylc/
\end{myitemize}

\paragraph[local index]{[documentation] \textrightarrow [[urls]] \textrightarrow local index}

Local intranet URL of the main cylc documentation index.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} (none)
\end{myitemize}

\subsection{[document viewers]}

PDF and HTML viewers can be launched by cylc to view the documentation.

\subsubsection[pdf]{[document viewers] \textrightarrow pdf}

Your preferred PDF viewer program.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} evince
\end{myitemize}

\subsubsection[html]{[document viewers] \textrightarrow html}

Your preferred web browser.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} firefox
\end{myitemize}

\subsection{[editors]}

Choose your favourite text editor for editing suite definitions.

\subsubsection[terminal]{[editors] \textrightarrow terminal}

The editor to be invoked by the cylc command line interface.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} \lstinline=vim=
\item {\em examples:}
    \begin{myitemize}
            \item \lstinline@terminal = emacs -nw@ (emacs non-GUI)
            \item \lstinline@terminal = emacs@ (emacs GUI)
            \item \lstinline@terminal = gvim -f@ (vim GUI)
    \end{myitemize}
\end{myitemize}

\subsubsection[gui]{[editors] \textrightarrow gui}

The editor to be invoked by the cylc GUI.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} \lstinline=gvim -f=
\item {\em examples:}
    \begin{myitemize}
            \item \lstinline@gui = emacs@
            \item \lstinline@gui = xterm -e vim@
    \end{myitemize}
\end{myitemize}


\subsection{[pyro]}

Pyro is the RPC layer used for network communication between cylc
clients (suite-connecting commands and guis) servers (running suites).
Each suite listens on a dedicated network port, binding on the first
available starting at the configured base port.

\subsubsection[base port]{[pyro] \textrightarrow base port }

The first port that cylc is allowed to use.

\begin{myitemize}
\item {\em type:} integer
\item {\em default:} 7766
\end{myitemize}

\subsubsection[maximum number of ports]{[pyro] \textrightarrow maximum number of ports}

This determines the maximum number of suites that can run at once on the
suite host.

\begin{myitemize}
\item {\em type:} integer
\item {\em default:} 100
\end{myitemize}

\subsubsection[ports directory]{[pyro] \textrightarrow ports directory}

Each suite stores its port number, by suite name, under this directory.

\begin{myitemize}
\item {\em type:} string (directory path)
\item {\em default:} \lstinline@$HOME/.cylc/ports/@
\end{myitemize}

\subsection{[monitor]}

Configurable settings for the command line \lstinline=cylc monitor= tool.

\subsubsection[monitor]{[monitor] \textrightarrow sort order}

The sort order for tasks in the monitor view.
\begin{myitemize}
    \item {\em type:} string
    \item {\em options:}
    \begin{myitemize}
        \item {\bf alphanumeric}
        \item {\bf definition} -  the order that tasks appear under
            \lstinline=[runtime]= in the suite definition.
    \end{myitemize}
    \item {\em default:} definition
\end{myitemize}

\subsection{[hosts]}

The [hosts] section configures some important host-specific settings for
the suite host (`localhost') and remote task hosts. Note that {\em
remote task behaviour is determined by the site/user config on the
suite host, not on the task host}. Suites can specify task hosts that
are not listed here, in which case local settings will be assumed,
with the local home directory path, if present, replaced by
\lstinline=$HOME= in items that configure directory locations.

\subsubsection[{[[}HOST{]]}]{[hosts] \textrightarrow [[HOST]]}

The default task host is the suite host, {\bf localhost}, with default
values as listed below. Use an explicit \lstinline=[hosts][[localhost]]=
section if you need to override the defaults. Localhost settings are
then also used as defaults for other hosts, with the local home
directory path replaced as described above. This applies to items
omitted from an explicit host section, and to hosts that are not listed
at all in the site and user config files.  Explicit host sections are only
needed if the automatically modified local defaults are not sufficient.

Host section headings can also be {\em regular expressions} to match
multiple hostnames.  Note that the general regular expression wildcard
is `\lstinline=.*=' (zero or more of any character), not
`\lstinline=*='.
Hostname matching regular expressions are used as-is in the Python
\lstinline=re.match()= function. As such they match from the beginning
of the hostname string (as specified in the suite definition) and they
do not have to match through to the end of the string (use the
string-end matching character `\lstinline=$=' in the expression to
force this).

A hierachy of host match expressions from specific to general can be
used because config items are processed in the order specified in the
file.

\begin{myitemize}
\item {\em type:} string (hostname or regular expression)
\item {\em examples:}
\begin{myitemize}
    \item \lstinline@server1.niwa.co.nz@ - explicit host name
    \item  \lstinline@server\d.niwa.co.nz@ - regular expression
\end{myitemize}
\end{myitemize}

\paragraph[run directory]{[hosts] \textrightarrow [[HOST]] \textrightarrow run directory }

The top level of the directory tree that holds suite-specific output logs,
run database, etc.

\begin{myitemize}
\item {\em type:} string (directory path)
\item {\em default:} \lstinline=$HOME/cylc-run=
\end{myitemize}

\paragraph[work directory]{[hosts] \textrightarrow [[HOST]] \textrightarrow work directory }
\label{workdirectory}

The top level for suite work and share directories.

\begin{myitemize}
\item {\em type:} string (directory path)
\item {\em localhost default:} \lstinline@$HOME/cylc-run@
\end{myitemize}


\paragraph[task communication method]{[hosts] \textrightarrow [[HOST]] \textrightarrow task communication method }
\label{task_comms_method}

The means by which task progress messages are reported back to the running suite.
See above for default polling intervals for the poll method.

\begin{myitemize}
\item {\em type:} string (must be one of the following three options)
\item {\em options:}
    \begin{myitemize}
    \item {\bf pyro} - direct client-server RPC via network ports
    \item {\bf ssh} - use ssh to re-invoke the Pyro messaging commands on the suite server
    \item {\bf poll} - the suite polls for the status of tasks (no task messaging)
  \end{myitemize}
\item {\em localhost default:} pyro
\end{myitemize}

\paragraph[remote copy template]{[hosts] \textrightarrow [[HOST]] \textrightarrow remote copy template }

A string for the command used to copy files to a remote host. This is not used
on the suite host unless you run local tasks under another user account.

\begin{myitemize}
\item {\em type:} string
\item {\em localhost default:} \lstinline@scp -oBatchMode=yes -oConnectTimeout=10@
\end{myitemize}

\paragraph[remote shell template]{[hosts] \textrightarrow [[HOST]] \textrightarrow remote shell template }

A string for the command used to invoke commands on this host.
This is not used on the suite host unless you run local tasks under
another user account. (N.B. This setting used to be a string template with a \%s
being a placeholder for the name of the host. This is no longer the case. Any
\%s in the string will now be discarded.)

\begin{myitemize}
\item {\em type:} string
\item {\em localhost default:} \lstinline@ssh -oBatchMode=yes -oConnectTimeout=10@
\end{myitemize}

\paragraph[use login shell]{[hosts] \textrightarrow [[HOST]] \textrightarrow use login shell }

Whether to use a login shell or not for remote command invocation. By
default cylc runs remote ssh commands using a login shell:
\begin{lstlisting}
  ssh user@host 'bash --login cylc ...'
\end{lstlisting}
which will source \lstinline=/etc/profile= and
\lstinline=~/.profile= to set up the user environment.  However, for
security reasons some institutions do not allow unattended commands to
start login shells, so you can turn off this behaviour to get:
\begin{lstlisting}
  ssh user@host 'cylc ...'
\end{lstlisting}
which will use the default shell on the remote machine,
sourcing \lstinline=~/.bashrc= (or \lstinline=~/.cshrc=) to set up the
environment.

\begin{myitemize}
\item {\em type:} boolean
\item {\em localhost default:} True
\end{myitemize}

\paragraph[cylc executable]{[hosts] \textrightarrow [[HOST]] \textrightarrow cylc executable }

The \lstinline=cylc= executable on a remote host. Note this should point to the
cylc multi-version wrapper (see~\ref{CUI}) on the host, not
\lstinline=bin/cylc= for a specific installed version.
Specify a full path if \lstinline=cylc= is not in \lstinline=\$PATH= when it is
invoked via \lstinline=ssh= on this host.

\begin{myitemize}
\item {\em type:} string
\item {\em localhost default:} \lstinline@cylc@
\end{myitemize}

\paragraph[global init-script]{[hosts] \textrightarrow [[HOST]] \textrightarrow global init-script }
\label{GlobalInitScript}

If specified, the value of this setting will be inserted to just before the
\lstinline=init-script= section of all job scripts that are to be
submitted to the specified remote host.

\begin{myitemize}
\item {\em type:} string
\item {\em localhost default:} \lstinline@""@
\end{myitemize}

\paragraph[copyable environment variables]{[hosts] \textrightarrow [[HOST]] \textrightarrow copyable environment variables }

A list containing the names of the environment variables that can and/or need
to be copied from the suite daemon to a job.

\begin{myitemize}
\item {\em type:} string\_list
\item {\em localhost default:} \lstinline@[]@
\end{myitemize}

\paragraph[retrieve job logs]{[hosts] \textrightarrow [[HOST]] \textrightarrow retrieve job logs}

Global default for the~\ref{runtime-remote-retrieve-job-logs} setting for the
specified host.

\paragraph[retrieve job logs command]{[hosts] \textrightarrow [[HOST]] \textrightarrow retrieve job logs command}

If \lstinline@rsync -a@ is unavailable or insufficient to retrieve job logs
from a remote host, you can use this setting to specify a suitable command.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} rsync -a
\end{myitemize}

\paragraph[retrieve job logs max size]{[hosts] \textrightarrow [[HOST]] \textrightarrow retrieve job logs max size}

Global default for the~\ref{runtime-remote-retrieve-job-logs-max-size} setting for the
specified host.

\paragraph[retrieve job logs retry delays]{[hosts] \textrightarrow [[HOST]] \textrightarrow retrieve job logs retry delays}

Global default for the~\ref{runtime-remote-retrieve-job-logs-retry-delays}
setting for the specified host.

\paragraph[task event handler retry delays]{[hosts] \textrightarrow [[HOST]] \textrightarrow task event handler retry delays}

Host specific default for the~\ref{runtime-events-handler-retry-delays}
setting.

\paragraph[local tail command template]{[hosts] \textrightarrow [[HOST]] \textrightarrow local tail command template}
\label{local-tail-template}

A template (with \lstinline=%(filename)s= substitution) for the command used to
tail-follow local job logs, used by the gcylc log viewer and
\lstinline=cylc cat-log --tail=.  You are unlikely to need to override this.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} \lstinline@tail -n +1 -F %(filename)s@
\end{myitemize}

\paragraph[remote tail command template]{[hosts] \textrightarrow [[HOST]] \textrightarrow remote tail command template}
\label{remote-tail-template}

A template (with \lstinline=%(filename)s= substitution) for the command used
to tail-follow remote job logs, used by the gcylc log viewer and
\lstinline=cylc cat-log --tail=.  The remote tail command needs to be told to
die when its parent process exits. You may need to override this command for
task hosts where the default \lstinline=tail= or \lstinline=ps= commands are
not equivalent to the Gnu Linux versions.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} \lstinline@tail --pid=$(ps h -o ppid $$ | sed -e 's/[[:space:]]//g') -n +1 -F %(filename)s@
\item {\em example:} for AIX hosts:\\
    \lstinline@/gnu/tail --pid=$(ps -o ppid= -p $$ | sed -e 's/[[:space:]]//g') -n +1 -F %(filename)s@
\end{myitemize}

\paragraph[{[[[}batch systems{]]]}]{[hosts] \textrightarrow [[HOST]] \textrightarrow [[[batch systems]]]}

Settings for particular batch systems on HOST. In the subsections below, SYSTEM
should be replaced with the cylc job submission method name that represents the
batch system (see~\ref{RuntimeJobSubMethods}).

\subparagraph[{[[[[}SYSTEM{]]]]}err tailer]{[hosts] \textrightarrow [[HOST]] \textrightarrow [[[batch systems]]] \textrightarrow [[[[SYSTEM]]]] \textrightarrow err tailer}
\label{err-tailer}

A command template (with \lstinline=%(job_id)s= substitution) that can be used
to tail-follow the stderr stream of a running job if SYSTEM does
not use the normal log file location while the job is running.  This setting
overrides~\ref{local-tail-template} and~\ref{remote-tail-template} above.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} (none)
\item {\em example:} For PBS:
    \begin{lstlisting}
[hosts]
    [[ myhpc*]]
        [[[batch systems]]]
            [[[[pbs]]]]
                err tailer = qcat -f -e %(job_id)s
                out tailer = qcat -f -o %(job_id)s
                err viewer = qcat -e %(job_id)s
                out viewer = qcat -o %(job_id)s
    \end{lstlisting}
\end{myitemize}

\subparagraph[{[[[[}SYSTEM{]]]]}out tailer]{[hosts] \textrightarrow [[HOST]] \textrightarrow [[[batch systems]]] \textrightarrow [[[[SYSTEM]]]] \textrightarrow out tailer}
\label{out-tailer}

A command template (with \lstinline=%(job_id)s= substitution) that can be used
to tail-follow the stdout stream of a running job if SYSTEM does
not use the normal log file location while the job is running.  This setting
overrides~\ref{local-tail-template} and~\ref{remote-tail-template} above.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} (none)
\item {\em example:} see~\ref{err-tailer}
\end{myitemize}

\subparagraph[{[[[[}SYSTEM{]]]]}err viewer]{[hosts] \textrightarrow [[HOST]] \textrightarrow [[[batch systems]]] \textrightarrow [[[[SYSTEM]]]] \textrightarrow err viewer}

A command template (with \lstinline=%(job_id)s= substitution) that can be used
to view the stderr stream of a running job if SYSTEM does
not use the normal log file location while the job is running.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} (none)
\item {\em example:} see~\ref{err-tailer}
\end{myitemize}

\subparagraph[{[[[[}SYSTEM{]]]]}out viewer]{[hosts] \textrightarrow [[HOST]] \textrightarrow [[[batch systems]]] \textrightarrow [[[[SYSTEM]]]] \textrightarrow out viewer}

A command template (with \lstinline=%(job_id)s= substitution) that can be used
to view the stdout stream of a running job if SYSTEM does
not use the normal log file location while the job is running.

\begin{myitemize}
\item {\em type:} string
\item {\em default:} (none)
\item {\em example:} see~\ref{err-tailer}
\end{myitemize}

\subparagraph[{[[[[}SYSTEM{]]]]}job name length maximum]{[hosts] \textrightarrow [[HOST]] \textrightarrow [[[batch systems]]] \textrightarrow [[[[SYSTEM]]]] \textrightarrow job name length maximum}
\label{JobNameLengthMaximum}

The maximum length for job name acceptable by a batch system on a given host.
Currently, this setting is only meaningful for PBS jobs. For example, PBS 12
or older will fail a job submit if the job name has more than 15 characters,
which is the default setting. If you have PBS 13 or above, you may want to
modify this setting to a larger value.

\begin{myitemize}
\item {\em type:} integer
\item {\em default:} (none)
\item {\em example:}  For PBS:
    \begin{lstlisting}
[hosts]
    [[myhpc*]]
        [[[batch systems]]]
            [[[[pbs]]]]
                # PBS 13
                job name length maximum = 236
    \end{lstlisting}
\end{myitemize}

\subparagraph[{[[[[}SYSTEM{]]]]}execution time limit polling intervals]{[hosts] \textrightarrow [[HOST]] \textrightarrow [[[batch systems]]] \textrightarrow [[[[SYSTEM]]]] \textrightarrow execution time limit polling intervals}
\label{ExecutionTimeLimitPollingIntervals}

The intervals between polling after a task job (submitted to the relevant batch
system on the relevant host) exceeds its execution time limit. The default
setting is PT1M, PT2M, PT7M. The accumulated times (in minutes) for these
intervals will be roughly 1, 1 + 2 = 3 and 1 + 2 + 7 = 10 after a task job
exceeds its execution time limit.

\begin{myitemize}
    \item {\em type:} Comma-separated list of ISO 8601 duration/interval
        representations, optionally {\em preceded} by multipliers.
    \item {\em default:} PT1M, PT2M, PT7M
    \item {\em example:}
    \begin{lstlisting}
[hosts]
    [[myhpc*]]
        [[[batch systems]]]
            [[[[pbs]]]]
                execution time limit polling intervals = 5*PT2M
    \end{lstlisting}
\end{myitemize}

\subsection{[suite host self-identification] }

The suite host's identity must be determined locally by cylc and passed
to running tasks (via \lstinline@$CYLC_SUITE_HOST@) so that task messages
can target the right suite on the right host.

%(TO DO: is it conceivable that different remote task hosts at the same
%site might see the suite host differently? If so we would need to be
%able to override the target in suite definitions.)

\subsubsection[method]{[suite host self-identification] \textrightarrow method }

This item determines how cylc finds the identity of the suite host. For
the default {\em name} method cylc asks the suite host for its host
name. This should resolve on remote task hosts to the IP address of the
suite host; if it doesn't, adjust network settings or use one of the
other methods. For the {\em address} method, cylc attempts to use a
special external ``target address'' to determine the IP address of the
suite host as seen by remote task hosts (in-source documentation in
\lstinline=$CYLC_DIR/lib/cylc/suite_host.py= explains how this works).
And finally, as a last resort, you can choose the {\em hardwired} method
and manually specify the host name or IP address of the suite host.

\begin{myitemize}
\item {\em type:} string
\item {\em options:}
\begin{myitemize}
    \item name - self-identified host name
    \item address - automatically determined IP address (requires {\em target}, below)
    \item hardwired - manually specified host name or IP address (requires {\em host}, below)
\end{myitemize}
\item {\em default:} name
\end{myitemize}

\subsubsection[target]{[suite host self-identification] \textrightarrow target }

This item is required for the {\em address} self-identification method.
If your suite host sees the internet, a common address such as
\lstinline@google.com@ will do; otherwise choose a host visible on your
intranet.
\begin{myitemize}
\item {\em type:} string (an inter- or intranet URL visible from the suite host)
\item {\em default:} \lstinline@google.com@
\end{myitemize}


\subsubsection[host]{[suite host self-identification] \textrightarrow host }

Use this item to explicitly set the name or IP address of the suite host
if you have to use the {\em hardwired} self-identification method.
\begin{myitemize}
\item {\em type:} string (host name or IP address)
\item {\em default:} (none)
\end{myitemize}

\subsection{[suite host scanning]}

Utilities such as \lstinline=cylc gsummary= need to scan hosts for
running suites.

\subsubsection[hosts]{[suite host scanning] \textrightarrow hosts }

A list of hosts to scan for running suites.
\begin{myitemize}
\item {\em type:} comma-separated list of host names or IP addresses.
\item {\em default:} localhost
\end{myitemize}

\subsection{[task events]}

Global site/user defaults for~\ref{TaskEventHandling}.

\subsection{[test battery]}

Settings for the automated development tests.

\subsubsection[remote host with shared fs]{[test battery] \textrightarrow remote host with shared fs}

The name of a remote host with shared HOME file system as the host running the
test battery.

\subsubsection[remote host with shared fs]{[test battery] \textrightarrow remote host}

The name of a remote host without shared HOME file system as the host running
the test battery.

\subsubsection[{[[}batch systems{]]}]{[test battery] \textrightarrow [[batch systems]]}

Settings for testing supported batch systems (job submission methods). The
tests for a batch system are only performed if the batch system is available on
the test host or a remote host accessible via SSH from the test host.

\paragraph[{[[[}SYSTEM{]]]}]{[test battery] \textrightarrow [[batch systems]] \textrightarrow [[[SYSTEM]]]}

SYSTEM is the name of a supported batch system with automated tests.
This can currently be "loadleveler", "lsf", "pbs", "sge" and/or "slurm".

\subparagraph[host]{[test battery] \textrightarrow [[batch systems]] \textrightarrow [[[SYSTEM]]] \textrightarrow host}

The name of a host where commands for this batch system is available. Use
"localhost" if the batch system is available on the host running the test
battery. Any specified remote host should be accessible via SSH from the host
running the test battery.

\subparagraph[err viewer]{[test battery] \textrightarrow [[batch systems]] \textrightarrow [[[SYSTEM]]] \textrightarrow err viewer}

The command template (with \lstinline=\%(job_id)s= substitution) for testing
the run time stderr viewer functionality for this batch system.

\subparagraph[out viewer]{[test battery] \textrightarrow [[batch systems]] \textrightarrow [[[SYSTEM]]] \textrightarrow out viewer}

The command template (with \lstinline=\%(job_id)s= substitution) for testing
the run time stdout viewer functionality for this batch system.

\subparagraph[{[[[[}directives{]]]]}]{[test battery] \textrightarrow [[batch systems]] \textrightarrow [[[SYSTEM]]] \textrightarrow [[[[directives]]]]}

The minimum set of directives that must be supplied to the batch system on the
site to initiate jobs for the tests.

\subsection{[cylc]}

Default values for entries in the suite.rc [cylc] section.

\subsubsection[UTC mode]{[cylc] \textrightarrow UTC mode}
\label{SiteUTCMode}

Allows you to set a default value for UTC mode in a suite at the site level.
See ~\ref{UTC-mode} for details.

\subsubsection[{[}events{]}]{[cylc] \textrightarrow [[events]]}
\label{SiteCylcHooks}

You can define site defaults for each of the following options, details
of which can be found under ~\ref{SuiteEventHandling}:

\subparagraph[handlers]{[cylc] \textrightarrow [[events]] \textrightarrow handlers}

\subparagraph[handler events]{[cylc] \textrightarrow [[events]] \textrightarrow handler events}

\subparagraph[startup handler]{[cylc] \textrightarrow [[events]] \textrightarrow startup handler}

\subparagraph[shutdown handler]{[cylc] \textrightarrow [[events]] \textrightarrow shutdown handler}

\subparagraph[mail events]{[cylc] \textrightarrow [[events]] \textrightarrow mail events}

\subparagraph[mail footer]{[cylc] \textrightarrow [[events]] \textrightarrow mail footer}

\subparagraph[mail from]{[cylc] \textrightarrow [[events]] \textrightarrow mail from}

\subparagraph[mail smtp]{[cylc] \textrightarrow [[events]] \textrightarrow mail smtp}

\subparagraph[mail to]{[cylc] \textrightarrow [[events]] \textrightarrow mail to}

\subparagraph[timeout handler]{[cylc] \textrightarrow [[events]] \textrightarrow timeout handler}

\subparagraph[timeout]{[cylc] \textrightarrow [[events]] \textrightarrow timeout}

\subparagraph[abort on timeout]{[cylc] \textrightarrow [[events]] \textrightarrow abort on timeout}

\subparagraph[stalled handler]{[cylc] \textrightarrow [[events]] \textrightarrow stalled handler}

\subparagraph[abort on stalled]{[cylc] \textrightarrow [[events]] \textrightarrow abort on stalled}

\subparagraph[inactivity handler]{[cylc] \textrightarrow [[events]] \textrightarrow inactivity handler}

\subparagraph[inactivity]{[cylc] \textrightarrow [[events]] \textrightarrow inactivity}

\subparagraph[abort on inactivity]{[cylc] \textrightarrow [[events]] \textrightarrow abort on inactivity}

\subsection{[authentication]}
\label{GlobalAuth}

Authentication of client programs with suite daemons can be configured here, and
overridden in suites if necessary (see~\ref{SuiteAuth}).

The suite-specific passphrase must be installed on a user's account to
authorize full control privileges (see~\ref{tutPassphrases}
and~\ref{ConnectionAuthentication}). In the future we plan to move to a more
traditional user account model so that each authorized user can have their own
password.

\subsubsection[public]{[authentication] \textrightarrow public}

This sets the client privilege level for public access - i.e.\ no suite passphrase
required.

\begin{myitemize}
\item {\em type:} string (must be one of the following options)
\item {\em options:}
    \begin{myitemize}
        \item {\em identity} - only suite and owner names revealed
        \item {\em description} - identity plus suite title and description
        \item {\em state-totals} - identity, description, and task state totals
        \item {\em full-read} - full read-only access for monitor and GUI
        \item {\em shutdown} - full read access plus shutdown, but no other
            control.
    \end{myitemize}
\item {\em default:} state-totals
\end{myitemize}

\subsubsection{[authentication] \textrightarrow hashes}

This sets the hash algorithms used for Pyro HMAC, which are used to
authenticate a client (e.g. gcylc) to the suite daemon. The first item is used
as the default hash. Subsequent items (if any) are used as fallback hashes
(e.g. for backwards compatibility with older suite daemons that are still
running with an alternative hash).

The default hashes are SHA-256 followed by MD5. You may want to exclude MD5 for
security reasons - e.g. for FIPS
(\url{https://en.wikipedia.org/wiki/FIPS_140-2}) compliance. Older cylc
versions use MD5.

SHA-256 and SHA-512 are the most secure. MD5 is popularly used for HMAC, but is
the least secure. SHA-1 is slightly better. Note that HMAC use is not as
susceptible to hash collision weakness, so both algorithms are more secure for
HMAC use than in the general case.

Clients will attempt to establish a connection using the algorithms from first
to last. The exceptions are scanning and pinging, which will use the algorithm
configured in the [authentication] \textrightarrow scan hash setting below. If
you have lots of suites running with e.g. MD5 hashes, you will want to include
'md5' in your list of hashes and set it as the default scan hash.

See \url{https://docs.python.org/2/library/hmac.html} and
\url{https://docs.python.org/2/library/hashlib.html} for discussion of hash
algorithms.

\begin{myitemize}
\item {\em type:} comma-separated list of hash names (must each be one of the
    following options)
\item {\em options:}
    \begin{myitemize}
        \item {\em sha256} - SHA-256 (recommended, default)
        \item {\em sha512} - SHA-512 (most secure, but slowest)
        \item {\em sha1} - SHA-1 (may be the best option on legacy systems)
        \item {\em md5} - MD5 (old default, usually used for HMAC, but the
            least secure)
    \end{myitemize}
\item {\em default:} sha256,md5
\end{myitemize}


\subsubsection{[authentication] \textrightarrow scan hash}

See [authentication] \textrightarrow hashes.

Configure which of the specified hash algorithms in [authentication]
\textrightarrow hashes is used for scanning and pinging (cylc scan, cylc ping).

The default hash algorithm for scans is MD5, for backwards compatibility
reasons. You can override it by specifying a different value for this setting
(e.g. for FIPS compliance).

The default will become SHA-256 sometime in 2016, when it is unlikely that any
old MD5 suites are still around.

\begin{myitemize}
\item {\em type:} hash name (must be one of the following options)
\item {\em options:}
    \begin{myitemize}
        \item {\em sha256} - SHA-256 (recommended, future default)
        \item {\em sha512} - SHA-512 (most secure, but slowest)
        \item {\em sha1} - SHA-1 (may be the best option on legacy systems)
        \item {\em md5} - MD5 (default, good for backwards compatibility, but
            the least secure)
    \end{myitemize}
\item {\em default:} md5
\end{myitemize}

