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 © 2009-2010 by Spectrum engineers:

    • Jan Kaluza <hanzz@soc.pidgin.im>
    • Mathias Ertl <mati@fsinf.at>
    • 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