diff options
| -rw-r--r-- | doc/doc.RPKI.CA.UI.GUI | 231 | ||||
| -rw-r--r-- | doc/doc.RPKI.CA.UI.GUI.Configuring | 84 | ||||
| -rw-r--r-- | doc/doc.RPKI.CA.UI.GUI.Configuring.Apache | 83 | ||||
| -rw-r--r-- | doc/doc.RPKI.CA.UI.GUI.Installing | 35 | ||||
| -rw-r--r-- | doc/doc.RPKI.CA.UI.GUI.Upgrading | 37 | ||||
| -rw-r--r-- | doc/doc.RPKI.CA.UI.GUI.Upgrading.BeforeMigration | 74 | ||||
| -rw-r--r-- | doc/doc.RPKI.CA.UI.GUI.UserModel | 129 | ||||
| -rw-r--r-- | doc/doc.RPKI.Installation | 3 | ||||
| -rw-r--r-- | doc/manual.pdf | bin | 493663 -> 515947 bytes |
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 Binary files differindex 91e5e778..c9be1d81 100644 --- a/doc/manual.pdf +++ b/doc/manual.pdf |