spectrumctl(8)                  Spectrum Manual                 spectrumctl(8)



NAME
       spectrumctl - Utility to control one or more spectrum instances

SYNOPSIS
       spectrumctl [options] action

DESCRIPTION
       The purpose of the spectrumctl utility is to control one or more
       Spectrum instances. Spectrum only handles one legacy network per
       instance, so you need more than one spectrum instance if you want
       support for more than one legacy network. The tool offers standard
       tasks usually performed by initscripts but also enables some runtime
       configuration of spectrum instances.

       An interactive shell with comfortable tab-completion is also supported
       to help with more complex administration tasks. See the SHELL for a
       detailed explanation.

ACTIONS
       By default, spectrumctl acts on all transports defined in
       /etc/spectrum/.  You can use a different directory with the --config-
       dir option. If you just want to act on a single file, you can use the
       --config option. Unless you use --config, spectrumctl will silently
       ignore files where the filename does not end with .cfg.

       start
           Start all instances. This command honours the enabled variable in
           the configuration file.

       stop
           Stop all instances. If an instance is already stopped but the pid-
           file exists, it is removed.

       restart
           Restart instances. This is essentially an alias for first calling
           stop and then start, so users will be disconnected when invoking
           this command.

       reload
           Reload instances. This just causes spectrum instances to reopen
           their log-files, it does not change any runtime configuration.
           Unlike restart, this command does not stop the transport, hence
           users will not notice anything.

       stats
           Print runtime statistics.

       upgrade-db
           Try to upgrade the database schema.

       message-all [path]
           Message all users that are currently online. The contents of the
           message come from the file located at path. If path is omitted or
           -, this command will read the message from standard input.

       register jid username [password] [language] [encoding]
           Register the user with JID jid and the legacy network account
           username. If the users default password, language and encoding are
           not given, this command will ask for these details interactivly.

           Note: It does not make sense to register a user across more than
           one transport, since a username is typically only valid within a
           single legacy network. This command will return an error if this
           shell currently represents more then one transport.

       unregister jid
           Unregister the user with JID jid. Note that unlike the register
           command, it makes sense to use this command accross many
           transports.

       set-vip-status jid status
           Set the VIP status of the user jid. The status should be "0" to
           disable VIP status and "1" to enable it.

       list
           List all selected transports along with their pid, protocol and
           hostname. If invoked with --quiet, this action does not print a
           header line and only prints the status for transports that are not
           currently runnning.

       cron
           Output transports that recently have crashed and create coredumps
           and log-files.

       help [cmd]
           Give help about the command cmd. If cmd is omitted, print a list of
           available commands.

OPTIONS
       -c FILE, --config=FILE
           Only act on transport configured in FILE (ignored for list)

       -d DIR, --config-dir=DIR
           Act on all transports configured in DIR (default: /etc/spectrum)

       -q, --quiet
           Do not print any output. For the list action, only print transports
           currently not running and do not print a header line.

       -h, --help
           show a help message and exit

       --version
           show program's version number and exit

       Options for action "list":

           --status=STATUS
               Only show transports with given status. Valid values are
               "running", "stopped" and "unknown"

           --machine-readable
               Output data as comma-seperated values.

           --cron
               This option is designed to make the list action suitable for
               periodic cron-runs. See the list action for more information.

       Options for action "start":

           --su=SU
               Start spectrum as this user (default: spectrum). Overrides the
               SPECTRUM_USER environment variable.  If neither --su nor the
               environment variable SPECTRUM_USER is specified, the user
               defaults to spectrum.

           --no-daemon
               Do not start spectrum as daemon.

           --debug
               Start spectrum in debug mode. Currently this just sets the
               maximum size of the core files to unlimited.

       Options for action "cron":

           --output-dir=DIR
               Output files to directory DIR (default: /root).

           --no-backtraces
               Do not create backtraces.

SHELL
       This tool also sports a fancy interactive shell that you can use to
       perform multiple administration tasks at once. You can launch the shell
       with the shell action. The shell features tab-completion for commands
       and a few commands only available within the shell.

       The prompt of the spectrumctl shell represents the transports that
       commands will act upon. If the shell acts upon all config-files defined
       in /etc/spectrum, the prompt will show <all transports> and the JID of
       the current transport otherwise.

       In addition to the actions defined above, spectrumctl also supports the
       following commands:

       load jid
           Only act upon the transport that serves jid. The prompt will be
           updated to reflect the change. If you use the special value all,
           all transports will be loaded again. Note that you cannot currently
           load config-files where the filename does not end with .cfg.

       exit
           Exit this shell

ENVIRONMENT
       The behaviour of spectrumctl can be influenced by the following
       environment variables:

       SPECTRUM_PATH
           Path where the spectrum binary is located. If omitted, spectrum is
           assumed to be in your PATH.

       SPECTRUM_USER
           The user with which spectrum is started. Overridden by the --su
           command line option.  If neither --su nor SPECTRUM_USER is
           specified, the user defaults to spectrum.

AUTHORS
       Copyright (C) 2009-2010 by Spectrum engineers:

       o   Jan Kaluza <hanzz@soc.pidgin.im>
       o   Mathias Ertl <mati@fsinf.at>
       o   Paul Aurich <paul@darkrain42.org>

       License GPLv3+: GNU GPL version 3 or later.  This is free software: you
       are free to change and redistribute it.  There is NO WARRANTY, to the
       extent permitted by law.

       See http://gnu.org/licenses/gpl.html for more information.

SEE ALSO
       spectrum(1), spectrum.cfg(5)

       For more information, see the spectrum homepage at http://spectrum.im/


BUGS
       Please submit bugs to our issue tracker at github:
       http://github.com/hanzz/spectrum/issues



Version 0.1-git                February 21, 2010                spectrumctl(8)
