1 ====================
2 Administration Guide
3 ====================
5 .. contents::
7 What does Roundup install?
8 ==========================
10 There's two "installations" that we talk about when using Roundup:
12 1. The installation of the software and its support files. This uses the
13 standard Python mechanism called "distutils" and thus Roundup's core code,
14 executable scripts and support data files are installed in Python's
15 directories. On Windows, this is typically:
17 Scripts
18 ``<python dir>\scripts\...``
19 Core code
20 ``<python dir>\lib\site-packages\roundup\...``
21 Support files
22 ``<python dir>\share\roundup\...``
24 and on Unix-like systems (eg. Linux):
26 Scripts
27 ``<python root>/bin/...``
28 Core code
29 ``<python root>/lib-<python version>/site-packages/roundup/...``
30 Support files
31 ``<python root>/share/roundup/...``
33 2. The installation of a specific tracker. When invoking the roundup-admin
34 "inst" (and "init") commands, you're creating a new Roundup tracker. This
35 installs configuration files, HTML templates, detector code and a new
36 database. You have complete control over where this stuff goes through
37 both choosing your "tracker home" and the ``main`` -> ``database`` variable
38 in the tracker's config.ini.
41 Configuring Roundup's Logging of Messages For Sysadmins
42 =======================================================
44 You may configure where Roundup logs messages in your tracker's config.ini
45 file. Roundup will use the standard Python (2.3+) logging implementation
46 when available. If not, then a very basic logging implementation will be used
47 (see BasicLogging in the roundup.rlog module for details).
49 Configuration for standard "logging" module:
50 - tracker configuration file specifies the location of a logging
51 configration file as ``logging`` -> ``config``
52 - ``roundup-server`` specifies the location of a logging configuration
53 file on the command line
54 Configuration for "BasicLogging" implementation:
55 - tracker configuration file specifies the location of a log file
56 ``logging`` -> ``filename``
57 - tracker configuration file specifies the level to log to as
58 ``logging`` -> ``level``
59 - ``roundup-server`` specifies the location of a log file on the command
60 line
61 - ``roundup-server`` specifies the level to log to on the command line
63 (``roundup-mailgw`` always logs to the tracker's log file)
65 In both cases, if no logfile is specified then logging will simply be sent
66 to sys.stderr with only logging of ERROR messages.
69 Configuring roundup-server
70 ==========================
72 The basic configuration file layout is as follows (take from the
73 ``roundup-server.ini.example`` file in the "doc" directory)::
75 [main]
76 port = 8080
77 ;hostname =
78 ;user =
79 ;group =
80 ;log_ip = yes
81 ;pidfile =
82 ;logfile =
83 ;template =
84 ;ssl = no
85 ;pem =
87 [trackers]
88 ; Add one of these per tracker being served
89 name = /path/to/tracker/name
91 Values ";commented out" are optional. The meaning of the various options
92 are as follows:
94 **port**
95 Defines the local TCP port to listen for clients on.
96 **hostname**
97 Defines the local hostname to listen for clients on. Only required if
98 "localhost" is not sufficient.
99 **user** and **group**
100 Defines the Unix user and group to run the server as. Only work if the
101 server is started as root.
102 **log_ip**
103 If ``yes`` then we log IP addresses against accesses. If ``no`` then we
104 log the hostname of the client. The latter can be much slower.
105 **pidfile**
106 If specified, the server will fork at startup and write its new PID to
107 the file.
108 **logfile**
109 Any unhandled exception messages or other output from Roundup will be
110 written to this file. It must be specified if **pidfile** is specified.
111 If per-tracker logging is specified, then very little will be written to
112 this file.
113 **template**
114 Specifies a template used for displaying the tracker index when
115 multiple trackers are being used. The variable "trackers" is available
116 to the template and is a dict of all configured trackers.
117 **ssl**
118 Enables the use of SSL to secure the connection to the roundup-server.
119 If you enable this, ensure that your tracker's config.ini specifies
120 an *https* URL.
121 **pem**
122 If specified, the SSL PEM file containing the private key and certificate.
123 If not specified, roundup will generate a temporary, self-signed certificate
124 for use.
125 **trackers** section
126 Each line denotes a mapping from a URL component to a tracker home.
127 Make sure the name part doesn't include any url-unsafe characters like
128 spaces. Stick to alphanumeric characters and you'll be ok.
131 Users and Security
132 ==================
134 Roundup holds its own user database which primarily contains a username,
135 password and email address for the user. Roundup *must* have its own user
136 listing, in order to maintain internal consistency of its data. It is a
137 relatively simple exercise to update this listing on a regular basis, or on
138 demand, so that it matches an external listing (eg. unix passwd file, LDAP,
139 etc.)
141 Roundup identifies users in a number of ways:
143 1. Through the web, users may be identified by either HTTP Basic
144 Authentication or cookie authentication. If you are running the web
145 server (roundup-server) through another HTTP server (eg. apache or IIS)
146 then that server may require HTTP Basic Authentication, and it will pass
147 the ``REMOTE_USER`` variable through to Roundup. If this variable is not
148 present, then Roundup defaults to using its own cookie-based login
149 mechanism.
150 2. In email messages handled by roundup-mailgw, users are identified by the
151 From address in the message.
153 In both cases, Roundup's behaviour when dealing with unknown users is
154 controlled by Permissions defined in the "SECURITY SETTINGS" section of the
155 tracker's ``schema.py`` module:
157 Web Registration
158 If granted to the Anonymous Role, then anonymous users will be able to
159 register through the web.
160 Email Registration
161 If granted to the Anonymous Role, then email messages from unknown users
162 will result in those users being registered with the tracker.
164 More information about how to customise your tracker's security settings
165 may be found in the `customisation documentation`_.
168 Tasks
169 =====
171 Maintenance of Roundup can involve one of the following:
173 1. `tracker backup`_
174 2. `software upgrade`_
175 3. `migrating backends`_
176 4. `moving a tracker`_
177 5. `migrating from other software`_
178 6. `adding a user from the command-line`_
181 Tracker Backup
182 --------------
184 The roundup-admin import and export commands are **not** recommended for
185 performing backup.
187 Optionally stop the web and email frontends and to copy the contents of the
188 tracker home directory to some other place using standard backup tools.
189 This means using
190 *pg_dump* to take a snapshot of your Postgres backend database, for example.
191 A simple copy of the tracker home (and files storage area if you've configured
192 it to be elsewhere) will then complete the backup.
195 Software Upgrade
196 ----------------
198 Always make a backup of your tracker before upgrading software. Steps you may
199 take:
201 1. Ensure that the unit tests run on your system::
203 python run_tests.py
205 2. If you're using an RDBMS backend, make a backup of its contents now.
206 3. Make a backup of the tracker home itself.
207 4. Stop the tracker web and email frontends.
208 5. Install the new version of the software::
210 python setup.py install
212 6. Follow the steps in the `upgrading documentation`_ for the new version of
213 the software in the copied.
215 Usually you will be asked to run `roundup_admin migrate` on your tracker
216 before you allow users to start accessing the tracker.
218 It's safe to run this even if it's not required, so just get into the
219 habit.
220 7. Restart your tracker web and email frontends.
222 If something bad happens, you may reinstate your backup of the tracker and
223 reinstall the older version of the sofware using the same install command::
225 python setup.py install
228 Migrating Backends
229 ------------------
231 1. Stop the existing tracker web and email frontends (preventing changes).
232 2. Use the roundup-admin tool "export" command to export the contents of
233 your tracker to disk.
234 3. Copy the tracker home to a new directory.
235 4. Delete the "db" directory from the new directory.
236 5. Enter the new backend name in the tracker home ``db/backend_name`` file.
237 6. Use the roundup-admin "import" command to import the previous export with
238 the new tracker home. If non-interactively::
240 roundup-admin -i <tracker home> import <tracker export dir>
242 If interactively, enter 'commit' before exitting.
243 7. Test each of the admin tool, web interface and mail gateway using the new
244 backend.
245 8. Move the old tracker home out of the way (rename to "tracker.old") and
246 move the new tracker home into its place.
247 9. Restart web and email frontends.
250 Moving a Tracker
251 ----------------
253 If you're moving the tracker to a similar machine, you should:
255 1. install Roundup on the new machine and test that it works there,
256 2. stop the existing tracker web and email frontends (preventing changes),
257 3. copy the tracker home directory over to the new machine, and
258 4. start the tracker web and email frontends on the new machine.
260 Most of the backends are actually portable across platforms (ie. from Unix to
261 Windows to Mac). If this isn't the case (ie. the tracker doesn't work when
262 moved using the above steps) then you'll need to:
264 1. install Roundup on the new machine and test that it works there,
265 2. stop the existing tracker web and email frontends (preventing changes),
266 3. use the roundup-admin tool "export" command to export the contents of
267 the existing tracker,
268 4. copy the export to the new machine,
269 5. use the roundup-admin "import" command to import the tracker on the new
270 machine, and
271 6. start the tracker web and email frontends on the new machine.
274 Migrating From Other Software
275 -----------------------------
277 You have a couple of choices. You can either use a CSV import into Roundup,
278 or you can write a simple Python script which uses the Roundup API
279 directly. The latter is almost always simpler -- see the "scripts"
280 directory in the Roundup source for some example uses of the API.
282 "roundup-admin import" will import data into your tracker from a
283 directory containing files with the following format:
285 - one colon-separated-values file per Class with columns for each property,
286 named <classname>.csv
287 - one colon-separated-values file per Class with journal information,
288 named <classname>-journals.csv (this is required, even if it's empty)
289 - if the Class is a FileClass, you may have the "content" property
290 stored in separate files from the csv files. This goes in a directory
291 structure::
293 <classname>-files/<N>/<designator>
295 where ``<designator>`` is the item's ``<classname><id>`` combination.
296 The ``<N>`` value is ``int(<id> / 1000)``.
299 Adding A User From The Command-Line
300 -----------------------------------
302 The ``roundup-admin`` program can create any data you wish to in the
303 database. To create a new user, use::
305 roundup-admin create user
307 To figure out what good values might be for some of the fields (eg. Roles)
308 you can just display another user::
310 roundup-admin list user
312 (or if you know their username, and it happens to be "richard")::
314 roundup-admin find username=richard
316 then using the user id you get from one of the above commands, you may
317 display the user's details::
319 roundup-admin display <userid>
322 Running the Servers
323 ===================
325 Unix
326 ----
328 On Unix systems, use the scripts/server-ctl script to control the
329 roundup-server server. Copy it somewhere and edit the variables at the top
330 to reflect your specific installation.
333 Windows
334 -------
336 On Windows, the roundup-server program runs as a Windows Service, and
337 therefore may be controlled through the Services control panel. The
338 roundup-server program may also control the service directly:
340 **install the service**
341 ``roundup-server -C /path/to/my/roundup-server.ini -c install``
342 **start the service**
343 ``roundup-server -c start``
344 **stop the service**
345 ``roundup-server -c stop``
347 To bring up the services panel:
349 Windows 2000 and later
350 Start/Control Panel/Administrative Tools/Services
351 Windows NT4
352 Start/Control Panel/Services
354 You will need a server configuration file (as described in
355 `Configuring roundup-server`_) for specifying tracker homes
356 and other roundup-server configuration. Specify the name of
357 this file using the ``-C`` switch when installing the service.
359 Running the Mail Gateway Script
360 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
362 The mail gateway script should be scheduled to run regularly on your
363 Windows server. Normally this will result in a window popping up. The
364 solution to this is to:
366 1. Create a new local account on the Roundup server
367 2. Set the scheduled task to run in the context of this user instead
368 of your normal login
371 .. _`customisation documentation`: customizing.html
372 .. _`upgrading documentation`: upgrading.html