$Id$ Portal GUI (web interface), written using the rpki Python libraries and the Django web development framework. This is still in early development, 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 portal-gui code makes: 1) There will be at least one resource holder which runs rpkid. In rpki parlance, it is "self-hosted." 2) The myrpki.py command line tool will handle all the heavy lifting, so it must be present on the installed system. In particular, mypki.py must be used to establish the parent/child relationships (n.b. in the future the portal-gui will have support for these functions as well.) 3) There is a subdirectory for each resource holder served by the portal-gui under ${localstatedir}/rpki/conf (typically this is /usr/local/var/rpki/conf). Each subdirectory contains the files associated with each resource holder (eg. rpki.conf). For example, if the portal gui is configured to serve Alice, Bob and Carol, the directory structure will look something like: /usr/local/var/rpki/conf/Alice/bpki/ /usr/local/var/rpki/conf/Alice/entitydb/ /usr/local/var/rpki/conf/Alice/rpki.conf /usr/local/var/rpki/conf/Bob/bpki/ /usr/local/var/rpki/conf/Bob/entitydb/ /usr/local/var/rpki/conf/Bob/rpki.conf /usr/local/var/rpki/conf/Carol/bpki/ /usr/local/var/rpki/conf/Carol/entitydb/ /usr/local/var/rpki/conf/Carol/rpki.conf NOTE: the ${localstatedir}/rpki/conf/ directory structure *MUST* be writable by the uid running apache. This is currently a restriction required due to some of bpki operations. The installation and user creation scripts attempt ensure this happens automatically, but if you are seeing permission denied errors, it is almost certainly due to files in this tree not being writable by the apache process. === Prerequisites === - install Django 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). Fedora: yum install Django - the portal-gui must be run using Apache with mod_wsgi Fedora: yum install httpd mod_wsgi - for security, mod_ssl is recommended Fedora: yum install mod_ssl ==== Installation === The portal-gui is configured and installed using the Makefile in the top level directory of the rpki tools. The configure script attempts to automatically determine which user the apache process runs as, but if it guesses incorrectly, you can override it with the WEBUSER= setting when running configure. For example: ./configure [ ... other options ...] WEBUSER=apache At the end of the installation process, the django-admin.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 not necessary, but is useful because you can use Django's admin views (via the /admin/ URL) to inspect the portal-gui's database directly, which may be useful for debugging. It also allows you to log into any of the resource handle accounts served by the portal-gui. (n.b. this superuser account should be different from the user account for the resource handle that is self-hosted on your rpkid). - configure Apache to serve the portal-gui See $top/portal-gui/README.apache === User Model === First, a word about the user model that the portal-gui uses. There is a single for each resource handle that rpkid serves, but these are distinct from the portal-gui user accounts. A single web user can manage multiple instances, or multiple users may manage a single instance (n.b. the web user creation script currently only handles a 1-to-1 mapping, but you can utilize the Django admin console to create additional users to manage the same instance.) === Creating Users === The portal-gui's security model allows the use of separate logins to manage each resource handle. Each resource handle needs to be configured to allow one or more users to manage it. This is accomplished by using the "rpkigui-add-user" script that is installed with the portal-gui in ${sbindir} (e.g. /usr/local/sbin). To create users, run the "rpkigui-add-user" script. The script takes three arguments: 1) the username for the new account, 2) the email address for the human that owns the account, and 3) the handle of the self-hosted resource holder who is hosting this user (for self-hosted users, specify the same username for the "host handle"). $ /usr/local/sbin/rpkigui-add-user where: is the name of the instance to manage (and also the web user login) is the web user's contact email address for the account is the name of the that is configured to host rpkid (i.e. has run_rpkid=True in its rpki.conf) In the case where you are creating the first web user that is self-hosting rpkid, the and will be the same. The email address is not currently used for anything; it just needs to be a valid RFC822 address. Example: # /usr/local/sbin/rpkigui-add-user Dave nobody@example.com John === Optional - Specify additional resource handles for a portal-gui user === You can configure which users are allowed to manage a particular resource handle once you have performed the "rpkigui-load-csv" step (described below) to populate the database: - navigate to http:///admin/app/conf/ - log in as the portal-gui superuser using the password you specified during the install step above - click on the link for the handle you wish to change - locate the "Owner" section - select one or more users to manage the handle - click on the "Save" button === 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 rpki.conf and .csv files and run: $ cd /usr/local/var/conf/ $ /usr/local/sbin/rpkigui-load-csv NOTE that you must run the "rpkigui-add-user" script *prior* to using "rpkigui-load-csv" or you will get errors because portal-gui won't yet know about which handles it is serving. You should run "rpkigui-load-csv" in *EACH* of your directories for each handle. === Starting the Portal GUI === If you have configured Django to use Apache and mod_wsgi, you just need to start your web server. Simply navigate to /rpki/ on your web server and you will be presented with the portal-gui's login page. === Logging in for first time, or after adding a new parent/child === The portal-gui does not automatically update its database when changes occur in the RPKI parent/child relationships (including RPKI rescert changes). Use the "Refresh" link the sidebar in the portal-gui to make the portal-gui query rpkid. For example, when you log in to the portal-gui after creating a user, you will notice that the parents/children section is empty. Assuming that you have given rpkid enough time to communicate via up-down to its parent, clicking "Refresh" should update the portal-gui's database. === Debugging Tips === The portal-gui is still in development. As such, problems may arise. Occasionally, portal-gui fails to appropriately validate data that it puts into its Django db. This may cause exceptions to be thrown, as the code assumes that data in the database is already valid. You can delete specific data from the Django database using Django's built-in admininstrative interface. It's available by navigating to the /admin/app/ URL and logging in as the superuser account. Here you will find a list of all the tables used by the portal-gui. If you are updating from the subversion repository, there may occasionally be changes in the portal-gui's database schema that require a complete reset of the database before it will function. Here are the steps for reseting to the initial state: $ django-admin.py reset --settings=rpki.gui.settings >>> answer "yes" to really reset it <<< $ cd /usr/local/var/rpki/conf/ $ /usr/local/libexec/rpkigui-add-user ... $ /usr/local/libexec/rpkigui-load-csv [ if applicable ]