1spectrumctl(8) Spectrum Manual spectrumctl(8)
2
6 spectrumctl - Utility to control one or more spectrum instances
7
9 spectrumctl [options] action
10
12 The purpose of the spectrumctl utility is to control one or more Spec‐
13 trum instances. Spectrum only handles one legacy network per instance,
14 so you need more than one spectrum instance if you want support for
15 more than one legacy network. The tool offers standard tasks usually
16 performed by initscripts but also enables some runtime configuration of
17 spectrum instances.
18 An interactive shell with comfortable tab-completion is also supported
20 to help with more complex administration tasks. See the SHELL for a
21 detailed explanation.
22
24 By default, spectrumctl acts on all transports defined in /etc/spec‐
25 trum/. You can use a different directory with the --config-dir option.
26 If you just want to act on a single file, you can use the --config
27 option. Unless you use --config, spectrumctl will silently ignore files
28 where the filename does not end with .cfg.
29 start
31 Start all instances. This command honours the enabled variable in
32 the configuration file.
33 stop
35 Stop all instances. If an instance is already stopped but the pid-
36 file exists, it is removed.
37 restart
39 Restart instances. This is essentially an alias for first calling
40 stop and then start, so users will be disconnected when invoking
41 this command.
42 reload
44 Reload instances. This just causes spectrum instances to reopen
45 their log-files, it does not change any runtime configuration.
46 Unlike restart, this command does not stop the transport, hence
47 users will not notice anything.
48 stats
50 Print runtime statistics.
51 upgrade-db
53 Try to upgrade the database schema.
54 message-all [path]
56 Message all users that are currently online. The contents of the
57 message come from the file located at path. If path is omitted or
58 -, this command will read the message from standard input.
59 register jid username [password] [language] [encoding]
61 Register the user with JID jid and the legacy network account user‐
62 name. If the users default password, language and encoding are not
63 given, this command will ask for these details interactivly.
64 Note: It does not make sense to register a user across more than
66 one transport, since a username is typically only valid within a
67 single legacy network. This command will return an error if this
68 shell currently represents more then one transport.
69 unregister jid
71 Unregister the user with JID jid. Note that unlike the register
72 command, it makes sense to use this command accross many trans‐
73 ports.
74 set-vip-status jid status
76 Set the VIP status of the user jid. The status should be "0" to
77 disable VIP status and "1" to enable it.
78 list
80 List all selected transports along with their pid, protocol and
81 hostname. If invoked with --quiet, this action does not print a
82 header line and only prints the status for transports that are not
83 currently runnning.
84 cron
86 Output transports that recently have crashed and create coredumps
87 and log-files.
88 help [cmd]
90 Give help about the command cmd. If cmd is omitted, print a list of
91 available commands.
92
94 -c FILE, --config=FILE
95 Only act on transport configured in FILE (ignored for list)
96 -d DIR, --config-dir=DIR
98 Act on all transports configured in DIR (default: /etc/spectrum)
99 -q, --quiet
101 Do not print any output. For the list action, only print transports
102 currently not running and do not print a header line.
103 -h, --help
105 show a help message and exit
106 --version
108 show program's version number and exit
109 Options for action "list":
111 --status=STATUS
113 Only show transports with given status. Valid values are "run‐
114 ning", "stopped" and "unknown"
115 --machine-readable
117 Output data as comma-seperated values.
118 --cron
120 This option is designed to make the list action suitable for
121 periodic cron-runs. See the list action for more information.
122 Options for action "start":
124 --su=SU
126 Start spectrum as this user (default: spectrum). Overrides the
127 SPECTRUM_USER environment variable. If neither --su nor the
128 environment variable SPECTRUM_USER is specified, the user
129 defaults to spectrum.
130 --no-daemon
132 Do not start spectrum as daemon.
133 --debug
135 Start spectrum in debug mode. Currently this just sets the max‐
136 imum size of the core files to unlimited.
137 Options for action "cron":
139 --output-dir=DIR
141 Output files to directory DIR (default: /root).
142 --no-backtraces
144 Do not create backtraces.
145
147 This tool also sports a fancy interactive shell that you can use to
148 perform multiple administration tasks at once. You can launch the shell
149 with the shell action. The shell features tab-completion for commands
150 and a few commands only available within the shell.
151 The prompt of the spectrumctl shell represents the transports that com‐
153 mands will act upon. If the shell acts upon all config-files defined in
154 /etc/spectrum, the prompt will show <all transports> and the JID of the
155 current transport otherwise.
156 In addition to the actions defined above, spectrumctl also supports the
158 following commands:
159 load jid
161 Only act upon the transport that serves jid. The prompt will be
162 updated to reflect the change. If you use the special value all,
163 all transports will be loaded again. Note that you cannot currently
164 load config-files where the filename does not end with .cfg.
165 exit
167 Exit this shell
168
170 The behaviour of spectrumctl can be influenced by the following envi‐
171 ronment variables:
172 SPECTRUM_PATH
174 Path where the spectrum binary is located. If omitted, spectrum is
175 assumed to be in your PATH.
176 SPECTRUM_USER
178 The user with which spectrum is started. Overridden by the --su
179 command line option. If neither --su nor SPECTRUM_USER is speci‐
180 fied, the user defaults to spectrum.
181
183 Copyright © 2009-2010 by Spectrum engineers:
184 · Jan Kaluza <hanzz@soc.pidgin.im>
186 · Mathias Ertl <mati@fsinf.at>
187 · Paul Aurich <paul@darkrain42.org>
188 License GPLv3+: GNU GPL version 3 or later. This is free software: you
190 are free to change and redistribute it. There is NO WARRANTY, to the
191 extent permitted by law.
192 See http://gnu.org/licenses/gpl.html for more information.
194
196 spectrum(1), spectrum.cfg(5)
197 For more information, see the spectrum homepage at http://spectrum.im/
199
202 Please submit bugs to our issue tracker at github:
203 http://github.com/hanzz/spectrum/issues
204Version 0.1-git February 21, 2010 spectrumctl(8)