spectrumctl

Langue: en

Version: February 21, 2010 (fedora - 01/12/10)

Section: 8 (Commandes administrateur)

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.
If invoked with the --cron option, this command only prints transports that are not running but where their pid file still exists. The pid files for those transports are removed. This allows you to run this command as a cron-job for watchdog purposes.

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.

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