diff options
Diffstat (limited to 'portal-gui/README')
| -rw-r--r-- | portal-gui/README | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/portal-gui/README b/portal-gui/README index 2491c3f5..daa72daa 100644 --- a/portal-gui/README +++ b/portal-gui/README @@ -10,3 +10,152 @@ about Django at http://www.djangoproject.com/ This package is an interface to rpkid and friends, so it assumes that you'll be running rpkid. If you haven't already done so, you should set up rpkid first; see ../rpkid/doc/Installation. + +=== Assumptions === + +This is a list of the assumptions the current rpkigui code makes: + +1) There will be at least one resource holder which runs rpkid. This handle + *must* be the parent of all other resource holders served by the same rpkid + instance. In rpki parlance, there is one "self-hosted" resource holder, and + all the others are "hosted." + +2) The myrpki.py command line tool will handle all the heavy lifting, so it must + be present on the installed system. + +3) All the directories containing the files assosiated with each + resource handle must reside in the same directory. That is, the + rpkigui expects the following structure: + + /datadir + /dad + /myrpki.conf + /entitydb/ + ... + /mom + /myrpki.conf + /entitydb/ + ... + /baby + /myrpki.conf + /entitydb/ + ... + +=== Installation === + +The web interface can be run out of the source directory for testing, or may be +deployed to work with an existing web server. Instructions for using Django +with Apache and mod_wsgi can be found at +http://docs.djangoproject.com/en/1.2/howto/deployment/modwsgi/#howto-deployment-modwsgi + +==== Configuation === + +The primary configuration file for the portal gui is +$top/portal-gui/rpkigui/settings.py. At a minimum, you will need to change the +default settings for the following variables: + +* DATABASE_NAME + This string variable should contain the full path for the sqlite +database that the portal GUI uses to store information. NOTE: this is a +different database from the one that rpkid uses. + +* SECRET_KEY + This string value should be set to a unique value for your installation. +There is no required format, but the longer the better. Something suitable +might be generated by running: + $ ps auxwww | sha1sum + +* TEMPLATE_DIRS + This is directory where the html templates for the various views in the +portal gui. Change the last entry to reflect your installation. + +* MYRPKI_DATA_DIR + The top level directory under which all the directories for your RPKI +handles are stored. Each directory must have a myrpki.conf file. + +* MYRPKI_SRC_DIR + The directory where myrpki.py command line tool can be found. + +There is one additional file that needs to be edited: +$top/portal-gui/rpkigui/urls.py. Near the end of the file is a dict entry for +"document_root." You must change the value to the full path for the directory +containing the image files used by the GUI. This can be a path into the +portal-gui source tree. + +=== Initialize === + +The next step is to initialize the sqlite database that the portal-gui uses to +store information. This is done using the "manage.py" wrapper script for +django: + $ cd $top/portal-gui/rpkigui/ + $ python manage.py syncdb + +The manage.py script will prompt you to create an administrative user if you +desire. The administrative user is useful because you can use django's admin +views to inspect the database directly, which may be useful for debugging. + +=== list_resources helper script === + +The portal-gui does not directly talk to the rpkid server. Instead, there is a +command line script named "list_resources" which talks to rpkid and updates the +portal-gui database with information that has changed. For testing purposes, +this script can be run by hand. However, for deployment you will need to set up +a cron job to run this script periodically for *each* resource handle the +portal-gui is serving. + +Note that "list_resources" only should be run in the directory where the +myrpki.conf for the resource handle that is self-hosting the rpkid. You may way +to create a script which is invoked by cron: + + #!/bin/sh + cd /var/lib/myrpki + $top/portal-gui/scripts/list_resources mom + $top/portal-gui/scripts/list_resources dad + $top/portal-gui/scripts/list_resources baby + +This script probably only needs to be run infrequently. It's sole purpose is to +query rpkid to ask what resources and children are configured for each resource +handle. This information does not change often. + +=== Load existing data === + +If you already have delegated resources to children, or created ROAs in the .csv +files for the myrpki.py command line tool, you will want to load the portal-gui +with this information. There is a helper script for doing this step. Simply +chdir to the directory containing your myrpki.conf and .csv files and run: + + $top/portal-gui/scripts/load_csv + +NOTE that you must run the "list_resources" script *prior* to using "load_csv" +or you will get errors because portal-gui won't yet know about which handles it +is serving. + +You should run "load_csv" in *each* of your directories for each handle. + +=== Starting the Portal GUI === + +If you have configured django to use apached and mod_wsgi, you just need to +start your web server. + +Alternatively, django comes with a test web server which is useful for small +deployments, or for just testing the portal-gui. You can start the test server +by running: + $ cd $top/portal-gui/rpkigui/ + $ python manage.py runserver <ip:port> +where <ip:port> is the address where you want to run the server. If you don't +specify the <ip:port>, the default is 127.0.0.1:8000. + +Now you can navigate to http://<ip:port>/myrpki/ to use the GUI. + +=== Creating Users === + +By default, the administrative user created during the "Initialization" step +above can manage all resource handles. However, the portal-gui's security model +allows the use of separate logins to manage resource handles. Each resource +handle needs to be configured to allow one or more users to manage it. This is +accomplished by using the django admin interface. http://<ip:port>/admin/ + +You can configure which users are allowed to manage a particular resource handle +by navigating to http://<ip:port>/admin/myrpki/conf/. Simply click on the +handle you want to change, and select one or more users in the "Owner" list box +and click "Save." |