Automatic pull of documentation from Wiki.

svn path=/trunk/; revision=5231

9 files changed, 448 insertions, 228 deletions

diff --git a/doc/doc.RPKI.CA.UI.GUI b/doc/doc.RPKI.CA.UI.GUI
index 8871d802..3017deea 100644
--- a/doc/doc.RPKI.CA.UI.GUI
+++ b/doc/doc.RPKI.CA.UI.GUI
@@ -1,230 +1,9 @@
-* wiki:GUI/UserModel
+****** Installing and Configuring ******
 
-****** GUI Installation ******
-
-These steps assume that you have already installed and configured the other CA
-tools.
-
-rpki-manage is a shell script wrapper around the django-admin command which
-sets $PYTHONPATH and $DJANGO_SETTINGS_MODULE.
-
-***** Prerequisites *****
-
-* Django 1.4 (Django 1.5 is not currently supported)
-
-* Django South 0.7.6 or later
-
-* Apache 2
-
-* mod_wsgi 3
-
-***** Upgrading from a Previous Release *****
-
-If you had previously installed the web portal before the database migration
-support was added, you will need to take some additional steps.
-
-**** Sync databases ****
-
-  $ rpki-manage syncdb
-
-Note that at the end of the syncdb output you will see the following message:
-
-  Not synced (use migrations):
-   - rpki.gui.app
-  (use ./manage.py migrate to migrate these)
-
-You should ignore the message about running ./manage.py since that script does
-not exist in our setup.
-
-**** Database Migration ****
-
-If you have not previously run the new database migration step, you will need
-to run this command. Note that you only need to run this command the first time
-you upgrade.
-
-  $ rpki-manage migrate app 0001 --fake
-
-If you are unsure whether or not you have previously run this command, you can
-verify with the following command:
-
-  $ rpki-manage migrate --list
-
-   app
-    (*) 0001_initial
-    (*) 0002_auto__add_field_resourcecert_conf
-    (*) 0003_set_conf_from_parent
-    (*) 0004_auto__chg_field_resourcecert_conf
-    (*) 0005_auto__chg_field_resourcecert_parent
-    ( ) 0006_add_conf_acl
-    ( ) 0007_default_acls
-
-The migrations are an ordered list. The presence of the asterisk (*) indicates
-that the migration has already been performed. ( ) indicates that the specific
-migration has not yet been applied. In the example above, migrations 0001
-through 0005 have been applied, but 0006 and 0007 have not.
-
-Now bring your database up to date with the current release:
-
-  $ rpki-manage migrate app
-
-From this point on you will just need to run the latter command every time you
-upgrade.
-
-Restart apache
-
-  $ apachectl restart
-
-***** New Installation *****
-
-**** Create the initial tables ****
-
-  $ rpki-manage syncdb
-
-Answer "yes" when asked if you want to create superuser Enter username for
-superuser Enter password
-
-Note that at the end of the syncdb output you will see the following message:
-
-  Not synced (use migrations):
-   - rpki.gui.app
-  (use ./manage.py migrate to migrate these)
-
-You should ignore the message about running ./manage.py since that script does
-not exist in our setup.
-
-If you need to create superuser at a later time, you can run
-
-  $ rpki-manage createsuperuser
-
-If you need to change superuser's password
-
-  $ rpki-manage changepassword <username>
-
-**** Perform Database Migration ****
-
-If there were any changes to the database schema, this command will bring your
-existing database up to date with the current software.
-
-  $ rpki-manage migrate app
-
-***** Configure Apache *****
-
-**** Ubuntu ****
-
-First, you need to install apache and enable SSL:
-
-  apt-get install apache2 libapache2-mod-wsgi
-  a2enmod ssl
-  a2ensite default-ssl
-
-Edit /etc/apache2/sites-enabled/default-ssl and place the following line inside
-the <VirtualHost> section:
-
-  Include /usr/share/rpki/apache.conf
-
-Now restart apache:
-
-  service apache2 restart
-
-**** FreeBSD ****
-
-Now configure apache, using /usr/local/etc/rpki/apache.conf, e.g.
-
-  $ cp apache.conf /usr/local/etc/apache22/Includes/rpki.conf
-
-On Ubuntu this will be
-
-  $ cp apache.conf /etc/apache2/conf.d/rpki.conf
-
-You can put it in a virtual host if you wish.
-
-Restart apache
-
-  $ apachectl restart
-
-Go to the URL for your web server and enter the superuser and password in login
-form.
-
-If you've only done the above bootstrap, there will only be a single handle to
-manage, so the GUI will automatically bring you to the dashboard for that
-handle.
-
-**** Running the web portal as a different user ****
-
-By default, the web portal is run in embedded mode in mod_wsgi, which means it
-runs inside the apache process. However, you can make the web portal run in
-daemon mode as a different user using mod_wsgi.
-
-  $ ./configure --enable-wsgi-daemon-mode[=user[:group]]
-
-Where user is the optional user to run the web portal as, and group is the
-optional group to run the web portal as. If user is not specified, it will run
-in a separate process but the same user as apache is configured to run.
-
-Note that when run in daemon mode, a unix domain socket will be created in the
-same directory as the apache log files. If the user you have specified to run
-the web portal as does not have permission to read a file in that directory,
-the web interface will return a 500 Internal Server Error and you will see a
-permission denied error in your apache logs. The solution to this is to use the
-WSGISocketPrefix apache configuration directive to specify an alternative
-location, such as:
-
-  WSGISocketPrefix /var/run/wsgi
-
-Note that this directive must not be placed inside of the VirtualHost section.
-It must be located at the global scope.
-
-see http://code.google.com/p/modwsgi/wiki/
-ConfigurationDirectives#WSGISocketPrefix for more information.
-
-****** Installation of Route Views Support for the GUI ******
-
-If you want ROA creation to tell the user what routes are in the global routing
-table for what they are about to create,
-
-Be sure you have curl installed. On FreeBSD it is in /usr/ports/ftp/curl
-
-Install a script such as the following as /usr/local/sbin/do-routeviews
-
-  #!/bin/sh
-  # Fetch the full bgp dump from routeviews.org and update the web
-  # portal's database
-  i=oix-full-snapshot-latest.dat.bz2
-  o=/tmp/$i
-  curl -s -S -o $o http://archive.routeviews.org/oix-route-views/$i
-  if [ $? -eq 0 ]; then
-     /usr/local/sbin/rpkigui-import-routes -l error $o
-  fi
-
-and create an entry in root's crontab such as
-
-  30  */2 *   *   *   root    /usr/local/sbin/do-routeviews
-
-If you want the GUI's "routes" page to see ROAs when you click those buttons,
-you will need to run rcynic. see the instructions for setting up rcynic.
-
-If you are running rootd, you may want to run with only your local trust
-anchor. In this case, to have the GUI be fairly responsive to changes, you may
-want to run the rcynic often. In this case, you may want to look at the value
-of jitter in rcynic.conf.
-
-In addition, your rcynic script should also have
-
-  /usr/local/sbin/rpkigui-rcynic -l error
-
-after the rcynic run.
-
-****** Expiration Checking ******
-
-The web portal can notify users when it detects that RPKI certificates will
-expire in the near future. Run the following script as a cron job, perhaps once
-a night:
-
-  /usr/local/sbin/rpkigui-check-expired
-
-By default it will warn of expiration 14 days in advance, but this may be
-changed by using the -t command line option and specifying how many days in
-advance to check.
+* GUI/Installing for new installs
+* GUI/Upgrading for upgrading from a previous install
+* GUI/Configuring
+* GUI/UserModel for instructions on managing users
 
 ****** Using the GUI ******
 
diff --git a/doc/doc.RPKI.CA.UI.GUI.Configuring b/doc/doc.RPKI.CA.UI.GUI.Configuring
new file mode 100644
index 00000000..026aa0e6
--- /dev/null
+++ b/doc/doc.RPKI.CA.UI.GUI.Configuring
@@ -0,0 +1,84 @@
+****** Configuring the Web Portal ******
+
+Also see doc/RPKI/CA/Configuration for documentation on the /etc/rpki.conf
+configuration file.
+
+***** Creating Users *****
+
+See doc/RPKI/CA/UI/GUI/UserModel
+
+***** Configuring Apache *****
+
+In order to use the web portal, Apache must be installed and configured to
+serve the application. See doc/RPKI/CA/UI/GUI/Configuring/Apache.
+
+***** Error Notifications via Email *****
+
+If an exception is generated while the web portal is processing a request, by
+default will be logged to the apache log file, and an email will be set to
+root@localhost. If you wish to change where email is sent, you can edit /etc/
+rpki/local_settings.py and add the following lines:
+
+  ADMINS = (('YOUR NAME', 'YOUR EMAIL ADDRESS'),)
+
+For example,
+
+  ADMINS = (('Joe User', 'joe@example.com'),)
+
+***** Cron Jobs *****
+
+The web portal makes use of some external data sources to display the
+validation status of routing entries. Therefore, it is necessary to run some
+background jobs periodically to refresh this data. The web portal software
+makes use of the cron facility present in POSIX operating systems to perform
+these tasks.
+
+**** Importing Routing Table Snapshot ****
+
+Requires: wget
+
+In order for the web portal to display the validation status of routes covered
+by a resource holder's RPKI certificates, it needs a source of the currently
+announced global routing table. The web portal includes a script which can
+parse the output of the RouteViews full snapshot (warning: links to very large
+file!).
+
+When the software is installed, there will be a /usr/local/share/routeviews.sh
+script that should be invoked periodically. Routeviews.org updates the snapshot
+every two hours, so it does not make sense to run it more frequently than two
+hours. How often to run it depends on how often the routes you are interested
+in are changing.
+
+Create an entry in root's crontab such as
+
+  30  */2 *   *   *      /usr/local/share/routeviews.sh
+
+**** Importing ROAs ****
+
+If you want the GUI's "routes" page to see ROAs when you click those buttons,
+you will need to run rcynic. see the instructions for setting up rcynic.
+
+This data is imported by the rcynic-cron script. If you have not already set up
+that cron job, you should do so now. Note that by default, rcynic-cron is run
+once an hour. What this means is that the routes view in the GUI will not
+immediately update as you create/destroy ROAs. You may wish to run rcynic-cron
+more frequently, or configure rcynic.conf to only include the TAL that is the
+root of your resources, and run the script more frequently (perhaps every 2-
+5 minutes).
+
+If you are running rootd, you may want to run with only your local trust
+anchor. In this case, to have the GUI be fairly responsive to changes, you may
+want to run the rcynic often. In this case, you may want to look at the value
+of jitter in rcynic.conf.
+
+**** Expiration Checking ****
+
+The web portal can notify users when it detects that RPKI certificates will
+expire in the near future. Run the following script as a cron job, perhaps once
+a night:
+
+  /usr/local/sbin/rpkigui-check-expired
+
+By default it will warn of expiration 14 days in advance, but this may be
+changed by using the -t command line option and specifying how many days in
+advance to check.
diff --git a/doc/doc.RPKI.CA.UI.GUI.Configuring.Apache b/doc/doc.RPKI.CA.UI.GUI.Configuring.Apache
new file mode 100644
index 00000000..cc50be4e
--- /dev/null
+++ b/doc/doc.RPKI.CA.UI.GUI.Configuring.Apache
@@ -0,0 +1,83 @@
+****** Apache Configuration ******
+
+This page documents how to configure Apache to server the web portal
+application.
+
+During the software install process, /usr/local/etc/rpki/apache.conf is
+created, which needs to be included from the apache configuration inside of a
+VirtualHost section.
+
+Note that the web portal application requires TLS to be enabled for the
+VirtualHost it is configured in, otherwise it will fail to operate.
+
+***** Requirements *****
+
+* Apache 2.2 or later
+* mod_ssl
+* mod_wsgi 3 or later
+
+***** Ubuntu *****
+
+First, you need to install apache and enable SSL. Run the following commands in
+a shell as root:
+
+  apt-get install apache2 libapache2-mod-wsgi
+  a2enmod ssl
+  a2ensite default-ssl
+
+Edit /etc/apache2/sites-enabled/default-ssl and place the following line inside
+the <VirtualHost> section:
+
+  Include /usr/local/etc/rpki/apache.conf
+
+Now restart apache:
+
+  service apache2 restart
+
+***** FreeBSD *****
+
+Now configure apache, using /usr/local/etc/rpki/apache.conf, e.g.
+
+  $ cp apache.conf /usr/local/etc/apache22/Includes/rpki.conf
+
+Restart apache
+
+  $ apachectl restart
+
+***** Running the web portal as a different user (optional) *****
+
+By default, the web portal is run in embedded mode in mod_wsgi, which means it
+runs inside the apache process. However, you can make the web portal run in
+daemon mode as a different user using mod_wsgi.
+
+  $ ./configure --enable-wsgi-daemon-mode[=user[:group]]
+
+Where user is the optional user to run the web portal as, and group is the
+optional group to run the web portal as. If user is not specified, it will run
+in a separate process but the same user as apache is configured to run.
+
+Note that when run in daemon mode, a unix domain socket will be created in the
+same directory as the apache log files. If the user you have specified to run
+the web portal as does not have permission to read a file in that directory,
+the web interface will return a 500 Internal Server Error and you will see a
+permission denied error in your apache logs. The solution to this is to use the
+WSGISocketPrefix apache configuration directive to specify an alternative
+location, such as:
+
+  WSGISocketPrefix /var/run/wsgi
+
+Note that this directive must not be placed inside of the VirtualHost section.
+It must be located at the global scope.
+
+see http://code.google.com/p/modwsgi/wiki/
+ConfigurationDirectives#WSGISocketPrefix for more information.
+
+***** Verify the Web Portal is Working *****
+
+Navigate to https://YOURHOST/rpki/ and you should see the login page for the
+web portal.
+
+Enter the superuser and password in login form (see doc/RPKI/CA/UI/GUI/
+UserModel if you haven't yet created a superuser). If you've only done the
+above bootstrap, there will only be a single handle to manage, so the GUI will
+automatically bring you to the dashboard for that handle.
diff --git a/doc/doc.RPKI.CA.UI.GUI.Installing b/doc/doc.RPKI.CA.UI.GUI.Installing
new file mode 100644
index 00000000..df52fdc2
--- /dev/null
+++ b/doc/doc.RPKI.CA.UI.GUI.Installing
@@ -0,0 +1,35 @@
+****** Installing the Web Portal for the First Time ******
+
+This page documents how to install the web portal software. If you have
+previously installed the software, see doc/RPKI/CA/UI/GUI/Upgrading for
+instructions.
+
+***** Prerequisites *****
+
+This page assumes that you have already followed the steps to install the CA
+software (see doc/RPKI/Installation)
+
+This page assumes that you have already created /etc/rpki.conf (see doc/RPKI/
+CA/Configuration)
+
+***** Create Database Tables *****
+
+This step creates the tables used by the web portal in the database. Run the
+following commands in the shell (you do not need to be root, just have
+permission to read /etc/rpki.conf):
+
+  rpki-manage syncdb --noinput
+  rpki-manage migrate
+
+Note that at the end of the syncdb output you will see the following message:
+
+  Not synced (use migrations):
+   - rpki.gui.app
+  (use ./manage.py migrate to migrate these)
+
+You should ignore the message about running ./manage.py since that script does
+not exist in our setup (we use rpki-manage instead`).
+
+***** Next Step *****
+
+See doc/RPKI/CA/UI/GUI/Configuring
diff --git a/doc/doc.RPKI.CA.UI.GUI.Upgrading b/doc/doc.RPKI.CA.UI.GUI.Upgrading
new file mode 100644
index 00000000..4d17d910
--- /dev/null
+++ b/doc/doc.RPKI.CA.UI.GUI.Upgrading
@@ -0,0 +1,37 @@
+****** Upgrading from a Previous Version ******
+
+* See wiki:doc/RPKI/CA/UI/GUI/Upgrading/BeforeMigration for the special
+  situation where you are upgrading from a release prior to database migration
+  support being added.
+
+This page describes the steps you must take if you upgrading from a previous
+version of the software that is already installed on the system. If you are
+installing for the first time see doc/RPKI/CA/UI/GUI/Installing.
+
+Run the following commands at a shell prompt. Note that you do not need run
+these as the root user, any user with permission to read /etc/rpki.conf is
+sufficient.
+
+  rpki-manage syncdb
+  rpki-manage migrate
+
+Note that at the end of the syncdb output you will see the following message:
+
+  Not synced (use migrations):
+   - rpki.gui.app
+  (use ./manage.py migrate to migrate these)
+
+You should ignore the message about running ./manage.py since that script does
+not exist in our setup (we use rpki-manage instead`).
+
+***** Restart Apache *****
+
+In order to cause Apache to reload the web portal software using the newly
+installed software, it must be restarted. Execute the following command as root
+in a shell:
+
+  apachectl restart
+
+***** Next Step *****
+
+See doc/RPKI/CA/UI/GUI/Configuring
diff --git a/doc/doc.RPKI.CA.UI.GUI.Upgrading.BeforeMigration b/doc/doc.RPKI.CA.UI.GUI.Upgrading.BeforeMigration
new file mode 100644
index 00000000..a9ef46c2
--- /dev/null
+++ b/doc/doc.RPKI.CA.UI.GUI.Upgrading.BeforeMigration
@@ -0,0 +1,74 @@
+****** Upgrading from a Previous Release without Migration Support ******
+
+This page documents the steps required to upgrade the web portal when you have
+a previous version of the software install prior to migration support via
+Django South. Note that this is a special case and will not apply to most
+situations (see doc/RPKI/CA/UI/GUI/Upgrading for the normal upgrade path). If
+you have already performed the steps on this page previously, then it does not
+apply to your situation.
+
+If you are unsure whether or not you have previously run this command, you can
+verify with the following command:
+
+  $ rpki-manage migrate --list
+
+   app
+    (*) 0001_initial
+    (*) 0002_auto__add_field_resourcecert_conf
+    (*) 0003_set_conf_from_parent
+    (*) 0004_auto__chg_field_resourcecert_conf
+    (*) 0005_auto__chg_field_resourcecert_parent
+    ( ) 0006_add_conf_acl
+    ( ) 0007_default_acls
+
+The migrations are an ordered list. The presence of the asterisk (*) indicates
+that the migration has already been performed. ( ) indicates that the specific
+migration has not yet been applied. In the example above, migrations 0001
+through 0005 have been applied, but 0006 and 0007 have not.
+
+***** Sync databases *****
+
+Execute the following command in a shell. Note that you do not need to be the
+root user, any user with permission to read /etc/rpki.conf is sufficient.
+
+  $ rpki-manage syncdb
+
+Note that at the end of the syncdb output you will see the following message:
+
+  Not synced (use migrations):
+   - rpki.gui.app
+  (use ./manage.py migrate to migrate these)
+
+You should ignore the message about running ./manage.py since that script does
+not exist in our setup.
+
+***** Initial Database Migration *****
+
+For a completely new install, there will not be any existing tables in the
+database, and the rpki-manage migrate command will create them. However, in the
+special situation where you are upgrading from a previous release prior to the
+migration support being added, you will already have the tables created, which
+will case the initial migration to fail. In order to work around this problem,
+we have to tell the migration that the initial step has already been performed.
+This is accomplished via the use the --fake command line argument:
+
+  $ rpki-manage migrate app 0001 --fake
+
+Note that this step doesn't actually modify the database, other than to record
+that the migration has already taken place.
+
+***** Database Migration *****
+
+Now bring your database up to date with the current release:
+
+  $ rpki-manage migrate
+
+From this point forward you will follow the steps in doc/RPKI/CA/UI/GUI/
+Upgrading each time you upgrade.
+
+***** Restart Apache *****
+
+In order to make Apache use the new version of the software, it must be
+restarted:
+
+  $ apachectl restart
diff --git a/doc/doc.RPKI.CA.UI.GUI.UserModel b/doc/doc.RPKI.CA.UI.GUI.UserModel
new file mode 100644
index 00000000..74575fdc
--- /dev/null
+++ b/doc/doc.RPKI.CA.UI.GUI.UserModel
@@ -0,0 +1,129 @@
+****** RPKI Web Portal User Model ******
+
+***** Roles *****
+
+The web portal uses a model where users are distinct from resource holders.
+
+**** Users ****
+
+A user is an entity that is granted permission to utilize the web portal. Each
+user account has an associated password that is used to log in to the web
+portal.
+
+The web portal maintains an access control list that specifies which resource
+holders the user is allowed to manage. If a user is authorized to manage more
+than a single resource holder, the user will be presented with a list of the
+resource holders upon login.
+
+Database tables: irdbd.auth_user and irdbd.app_confacl
+
+*** Changing User Passwords ***
+
+The password for a user may be changed via the web portal, or on the command
+line:
+
+  $ rpki-manage changepassword <USER>
+
+*** Superuser ***
+
+A user account with the superuser bit set has the special capability that it
+may assume the role of any resource holder managed by the local RPKI service.
+Superusers are created via the command line interface:
+
+  $ rpki-manage createsuperuser
+
+*** Creating user accounts ***
+
+When logged into the web portal with a #superuser account, select the web users
+link in the sidebar, and then click on the create button at the bottom of the
+page. You may optionally select one or more resource holders that this user is
+granted authorization to manage.
+
+Note that creating a user does not create a matching #resource-holder. See
+creating resource holders.
+
+*** Destroying user accounts ***
+
+When logged into the web portal with a #superuser account, select the web users
+link in the sidebar, and then click on the Delete icon next to the user you
+wish to delete.
+
+Note that this action does not remove any of the resource holders the user is
+granted authorization to manage.
+
+**** Resource Holders ****
+
+Resource holders are entities that have authority to manage a set of Internet
+number resources. When a user logs into the web portal, they select which
+resource holder role to assume. The user may choose to assume the role of a
+different resource holder by clicking on the select identity link in the
+sidebar.
+
+The list of resource holders managed by the local RPKI service can be viewed
+with a #superuser account by clicking on the resource holders link in the
+sidebar of the web portal. From this page the super can manage the resource
+holders.
+
+Database table: irdbd.irdb_resourceholderca (via irdbd.app_conf proxy model)
+
+*** Creating resource holders ***
+
+Note that creating a new resource holder does not create a user account. See
+#create-user.
+
+** GUI **
+
+When logged into the web portal with a #superuser account, select the resource
+holders link in the sidebar, and then click on the create button at the bottom
+of the page.
+
+If the new resource holder is going to be a child of another resource holder
+hosted by the local RPKI service, you may optionally select the parent resource
+holder from the dropdown box, and the parent-child relationship will
+automatically be established when the new resource holder is created.
+
+Additionally, one or more #users authorized to manage the new resource holder
+may be selected from the Users list on the creation form.
+
+** Command Line **
+
+You can also create resource holders on the command line:
+
+  $ rpkic -i <HANDLE> initialize
+  $ rpkic synchronize
+
+where HANDLE is the name of new resource holder. Note that this new resource
+holder will initially only be allowed to be managed by #superuser accounts. You
+may wish to create a matching user account, but the name of the user need not
+be the same as the handle of the resource holder. Additionally, you can manage
+the list of users allowed to manage this resource holder via the web portal;
+click on the Edit icon next to the resource holder, and select the users you
+wish to grant permission to manage.
+
+*** Destroying resource holders ***
+
+Note that deleting a resource holder does not remove any user accounts.
+
+** GUI **
+
+When logged into the web portal with a #superuser account, select the resource
+holders link in the sidebar, and then click on the delete button next to the
+resource holder you wish to delete.
+
+** Command Line **
+
+Or you may use the command line interface:
+
+  $ rpkic -i <HANDLE> delete_self
+  $ rpkic synchronize
+
+where HANDLE is the name of the resource holder you wish to destroy.
+
+*** Modifying the User ACL ***
+
+Each resource holder may be managed by one or more user accounts. The list of
+users authorized to assume the role of a particular resource holder may be
+changed in the web portal. When logged into the web portal with a #superuser
+account, select the resource holders link in the sidebar, and then click on the
+Edit icon next to the resource holder, and select the users you wish to grant
+permission to manage.
diff --git a/doc/doc.RPKI.Installation b/doc/doc.RPKI.Installation
index 616284b7..e56c910f 100644
--- a/doc/doc.RPKI.Installation
+++ b/doc/doc.RPKI.Installation
@@ -99,8 +99,7 @@ Packages you will need:
   o Ubuntu: python-mysqldb
 
 * http://www.djangoproject.com/, the Django web user interface toolkit. The GUI
-  interface to the CA tools requires this. Django 1.4 is required. Django 1.5
-  is currently not supported.
+  interface to the CA tools requires this. Django 1.4 is required.
 
   o FreeBSD: /usr/ports/www/py-django (py27-django)
   o Ubuntu: Do not use the python-django package (Django 1.3.1) in 12.04 LTS,
diff --git a/doc/manual.pdf b/doc/manual.pdf
index 91e5e778..c9be1d81 100644
--- a/doc/manual.pdf
+++ b/doc/manual.pdf