Managing Spectrum instances¶

spectrumctl is a tool written in Python which can be used to control instances of the Spectrum XMPP transport. 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. By default, spectrumctl acts on all transports defined in /etc/spectrum/.

Spectrumctl offers a few command-line options, please invoke it with --help to get a list of available options.

Spectrumctl Commands¶

spectrumctl supports a wide range of commands to control your spectrum instances.

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

Message all users that are currently online. If message starts with "file:" it will take the remaining part as path and sends its contents instead.

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 you don't specify a single config-file using the --config option.

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.

help [cmd]

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

Examples¶

Start all Spectrum instances (defined by config files in /etc/spectrum directory)

spectrumctl start

Stop all Spectrum instances (defined by config files in /etc/spectrum directory)

spectrumctl stop

Restart a single instance defined in a specific configuration file:

spectrumctl -c /etc/spectrum/yahoo.cfg restart

Unregister a user on all transports:

spectrumctl unregister user@example.com