$Id$ Portal GUI (web interface), written using the rpki Python libraries and the Django web development framework. This is still in early development, real installation directions haven't been written yet, but there's a lot of general information 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/ ... === Prerequisites === First, you must install Django 1.2 or greater on your system (django 1.1 may work, but you will need to disable to CsrfMiddleware in settings.py). 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 ==== Installation === The portal-gui is configured via the use of the supplied "configure" script. There are several required options: --with-myrpki=DIR specifies the full path to where the myrpki.py command line script and the rpki Python module can be located. CONFDIR=PATH specify the toplevel directory containing the subdirectories for each resource holder served by myrpki. Optional: --prefix=DIR use an alternate install tree. Defaults to /usr/local. DATABASE_PATH=PATH specifies the full pathname for the sqlite database used to back the portal gui. Defaults to /usr/local/var/portal-gui/rpkiop. --with-python=PATH specifies the full path to the python interpreter to use. Defaults to python2.6, python2.5, or python, in order. Example: ./configure --with-python=/usr/local/bin/python \ --with-myrpki=/home/me/src/rpki/rpkid \ CONFDIR=/home/me/myrpki \ DATABASE_PATH=/home/me/myrpki/rpkiop Once the portal-gui has been configured, the next step is to install it: $ make install At the end of the installation process, the manage.py script will prompt you to create a superuser. You want to say "yes" to this prompt. The superuser account can be named whatever you want. The superuser account is required to set up normal user accounts for managing resource handles. The superuser is also 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. NOTE that "list_resources" *must* be run in the directory where the myrpki.conf for the resource handle that is self-hosting the rpkid. Alternatively, you can set the $MYRPKI_CONF environment variable to full pathname of the myrpki.conf for the self-hosted resource handle (However, in order for this to work, you need to specify the full path name for "bpki_servers_directory" variable in your myrpki.conf.) You may way to create a script which is invoked by cron: #!/bin/sh cd /var/lib/myrpki/ # where the myrpki.conf for rpkid lives $top/portal-gui/scripts/list_resources 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: $top/portal-gui/scripts/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:///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:///admin/ You can configure which users are allowed to manage a particular resource handle by navigating to http:///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."