X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=doc%2Fadmin_guide.txt;h=95a15a8281a7d5a078e65b352b381cce791e441d;hb=56e200d63c6098917037aee2587915a26afd1f8f;hp=63a676f7e2093ad7b86184499b61e3efe4d3b49b;hpb=f519ddb7ada520d15242afea922a3900fb134523;p=roundup.git diff --git a/doc/admin_guide.txt b/doc/admin_guide.txt index 63a676f..95a15a8 100644 --- a/doc/admin_guide.txt +++ b/doc/admin_guide.txt @@ -2,8 +2,6 @@ Administration Guide ==================== -:Version: $Revision: 1.3 $ - .. contents:: What does Roundup install? @@ -36,8 +34,98 @@ There's two "installations" that we talk about when using Roundup: "inst" (and "init") commands, you're creating a new Roundup tracker. This installs configuration files, HTML templates, detector code and a new database. You have complete control over where this stuff goes through - both choosing your "tracker home" and the DATABASE variable in - config.py. + both choosing your "tracker home" and the ``main`` -> ``database`` variable + in the tracker's config.ini. + + +Configuring Roundup's Logging of Messages For Sysadmins +======================================================= + +You may configure where Roundup logs messages in your tracker's config.ini +file. Roundup will use the standard Python (2.3+) logging implementation +when available. If not, then a very basic logging implementation will be used +(see BasicLogging in the roundup.rlog module for details). + +Configuration for standard "logging" module: + - tracker configuration file specifies the location of a logging + configration file as ``logging`` -> ``config`` + - ``roundup-server`` specifies the location of a logging configuration + file on the command line +Configuration for "BasicLogging" implementation: + - tracker configuration file specifies the location of a log file + ``logging`` -> ``filename`` + - tracker configuration file specifies the level to log to as + ``logging`` -> ``level`` + - ``roundup-server`` specifies the location of a log file on the command + line + - ``roundup-server`` specifies the level to log to on the command line + +(``roundup-mailgw`` always logs to the tracker's log file) + +In both cases, if no logfile is specified then logging will simply be sent +to sys.stderr with only logging of ERROR messages. + + +Configuring roundup-server +========================== + +The basic configuration file layout is as follows (take from the +``roundup-server.ini.example`` file in the "doc" directory):: + + [main] + port = 8080 + ;hostname = + ;user = + ;group = + ;log_ip = yes + ;pidfile = + ;logfile = + ;template = + ;ssl = no + ;pem = + + [trackers] + ; Add one of these per tracker being served + name = /path/to/tracker/name + +Values ";commented out" are optional. The meaning of the various options +are as follows: + +**port** + Defines the local TCP port to listen for clients on. +**hostname** + Defines the local hostname to listen for clients on. Only required if + "localhost" is not sufficient. +**user** and **group** + Defines the Unix user and group to run the server as. Only work if the + server is started as root. +**log_ip** + If ``yes`` then we log IP addresses against accesses. If ``no`` then we + log the hostname of the client. The latter can be much slower. +**pidfile** + If specified, the server will fork at startup and write its new PID to + the file. +**logfile** + Any unhandled exception messages or other output from Roundup will be + written to this file. It must be specified if **pidfile** is specified. + If per-tracker logging is specified, then very little will be written to + this file. +**template** + Specifies a template used for displaying the tracker index when + multiple trackers are being used. The variable "trackers" is available + to the template and is a dict of all configured trackers. +**ssl** + Enables the use of SSL to secure the connection to the roundup-server. + If you enable this, ensure that your tracker's config.ini specifies + an *https* URL. +**pem** + If specified, the SSL PEM file containing the private key and certificate. + If not specified, roundup will generate a temporary, self-signed certificate + for use. +**trackers** section + Each line denotes a mapping from a URL component to a tracker home. + Make sure the name part doesn't include any url-unsafe characters like + spaces. Stick to alphanumeric characters and you'll be ok. Users and Security @@ -64,7 +152,7 @@ Roundup identifies users in a number of ways: In both cases, Roundup's behaviour when dealing with unknown users is controlled by Permissions defined in the "SECURITY SETTINGS" section of the -tracker's ``dbinit.py`` module: +tracker's ``schema.py`` module: Web Registration If granted to the Anonymous Role, then anonymous users will be able to @@ -76,22 +164,32 @@ Email Registration More information about how to customise your tracker's security settings may be found in the `customisation documentation`_. + Tasks ===== Maintenance of Roundup can involve one of the following: -1. `tracker backup`_ +1. `tracker backup`_ 2. `software upgrade`_ 3. `migrating backends`_ 4. `moving a tracker`_ +5. `migrating from other software`_ +6. `adding a user from the command-line`_ Tracker Backup -------------- -Stop the web and email frontends and to copy the contents of the tracker home -directory to some other place using standard backup tools. +The roundup-admin import and export commands are **not** recommended for +performing backup. + +Optionally stop the web and email frontends and to copy the contents of the +tracker home directory to some other place using standard backup tools. +This means using +*pg_dump* to take a snapshot of your Postgres backend database, for example. +A simple copy of the tracker home (and files storage area if you've configured +it to be elsewhere) will then complete the backup. Software Upgrade @@ -100,34 +198,53 @@ Software Upgrade Always make a backup of your tracker before upgrading software. Steps you may take: -1. ensure that the unit tests run on your system -2. copy your tracker home to a new directory -3. follow the steps in the upgrading documentation for the new version of - the software -4. test each of the admin tool, web interface and mail gateway using the new - version of the software -5. stop the production web and email frontends -6. perform the upgrade steps on the existing tracker directory -7. upgrade the software -8. restart your tracker +1. Ensure that the unit tests run on your system:: + + python run_tests.py + +2. If you're using an RDBMS backend, make a backup of its contents now. +3. Make a backup of the tracker home itself. +4. Stop the tracker web and email frontends. +5. Install the new version of the software:: + + python setup.py install + +6. Follow the steps in the `upgrading documentation`_ for the new version of + the software in the copied. + + Usually you will be asked to run `roundup_admin migrate` on your tracker + before you allow users to start accessing the tracker. + + It's safe to run this even if it's not required, so just get into the + habit. +7. Restart your tracker web and email frontends. + +If something bad happens, you may reinstate your backup of the tracker and +reinstall the older version of the sofware using the same install command:: + + python setup.py install Migrating Backends ------------------ -1. stop the existing tracker web and email frontends (preventing changes) -2. use the roundup-admin tool "export" command to export the contents of - your tracker to disk -3. copy the tracker home to a new directory -4. change the backend used in the tracker home ``select_db.py`` file -5. delete the "db" directory from the new directory -6. use the roundup-admin "import" command to import the previous export with - the new tracker home -7. test each of the admin tool, web interface and mail gateway using the new - backend -8. move the old tracker home out of the way (rename to "tracker.old") and - move the new tracker home into its place -9. restart web and email frontends +1. Stop the existing tracker web and email frontends (preventing changes). +2. Use the roundup-admin tool "export" command to export the contents of + your tracker to disk. +3. Copy the tracker home to a new directory. +4. Delete the "db" directory from the new directory. +5. Enter the new backend name in the tracker home ``db/backend_name`` file. +6. Use the roundup-admin "import" command to import the previous export with + the new tracker home. If non-interactively:: + + roundup-admin -i import + + If interactively, enter 'commit' before exitting. +7. Test each of the admin tool, web interface and mail gateway using the new + backend. +8. Move the old tracker home out of the way (rename to "tracker.old") and + move the new tracker home into its place. +9. Restart web and email frontends. Moving a Tracker @@ -154,10 +271,102 @@ moved using the above steps) then you'll need to: 6. start the tracker web and email frontends on the new machine. -------------------- +Migrating From Other Software +----------------------------- -Back to `Table of Contents`_ +You have a couple of choices. You can either use a CSV import into Roundup, +or you can write a simple Python script which uses the Roundup API +directly. The latter is almost always simpler -- see the "scripts" +directory in the Roundup source for some example uses of the API. + +"roundup-admin import" will import data into your tracker from a +directory containing files with the following format: + +- one colon-separated-values file per Class with columns for each property, + named .csv +- one colon-separated-values file per Class with journal information, + named -journals.csv (this is required, even if it's empty) +- if the Class is a FileClass, you may have the "content" property + stored in separate files from the csv files. This goes in a directory + structure:: + + -files// + + where ```` is the item's ```` combination. + The ```` value is ``int( / 1000)``. -.. _`Table of Contents`: index.html -.. _`customisation documentation`: customizing.html +Adding A User From The Command-Line +----------------------------------- + +The ``roundup-admin`` program can create any data you wish to in the +database. To create a new user, use:: + + roundup-admin create user + +To figure out what good values might be for some of the fields (eg. Roles) +you can just display another user:: + + roundup-admin list user + +(or if you know their username, and it happens to be "richard"):: + + roundup-admin find username=richard + +then using the user id you get from one of the above commands, you may +display the user's details:: + + roundup-admin display + + +Running the Servers +=================== + +Unix +---- + +On Unix systems, use the scripts/server-ctl script to control the +roundup-server server. Copy it somewhere and edit the variables at the top +to reflect your specific installation. + + +Windows +------- + +On Windows, the roundup-server program runs as a Windows Service, and +therefore may be controlled through the Services control panel. The +roundup-server program may also control the service directly: + +**install the service** + ``roundup-server -C /path/to/my/roundup-server.ini -c install`` +**start the service** + ``roundup-server -c start`` +**stop the service** + ``roundup-server -c stop`` + +To bring up the services panel: + +Windows 2000 and later + Start/Control Panel/Administrative Tools/Services +Windows NT4 + Start/Control Panel/Services + +You will need a server configuration file (as described in +`Configuring roundup-server`_) for specifying tracker homes +and other roundup-server configuration. Specify the name of +this file using the ``-C`` switch when installing the service. + +Running the Mail Gateway Script +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The mail gateway script should be scheduled to run regularly on your +Windows server. Normally this will result in a window popping up. The +solution to this is to: + +1. Create a new local account on the Roundup server +2. Set the scheduled task to run in the context of this user instead + of your normal login + + +.. _`customisation documentation`: customizing.html +.. _`upgrading documentation`: upgrading.html