diff options
| -rw-r--r-- | rpkid/portal-gui/README | 207 | ||||
| -rw-r--r-- | rpkid/portal-gui/README.apache | 34 |
2 files changed, 0 insertions, 241 deletions
diff --git a/rpkid/portal-gui/README b/rpkid/portal-gui/README deleted file mode 100644 index fcffc43e..00000000 --- a/rpkid/portal-gui/README +++ /dev/null @@ -1,207 +0,0 @@ -$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=<username> 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 -<self/> for each resource handle that rpkid serves, but these are distinct from -the portal-gui user accounts. A single web user can manage multiple <self/> -instances, or multiple users may manage a single <self/> 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 -<self/> 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 <handle> <contact email> <host handle> - -where: - <handle> is the name of the <self/> instance to manage (and also the web user login) - <contact email> is the web user's contact email address for the account - <host handle> is the name of the <self/> 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 <handle> and <host handle> 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://<ip:port>/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/<handle> - $ /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/<directory containing rpki.conf for the self-hosted rpkid> - $ /usr/local/libexec/rpkigui-add-user ... - $ /usr/local/libexec/rpkigui-load-csv [ if applicable ] diff --git a/rpkid/portal-gui/README.apache b/rpkid/portal-gui/README.apache deleted file mode 100644 index 2955061a..00000000 --- a/rpkid/portal-gui/README.apache +++ /dev/null @@ -1,34 +0,0 @@ -$Id$ - -This file details how to configure apache+mod_wsgi to serve the -portal-gui. - -The web interface must 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 - -Setup -===== - -- Follow the steps in detailed in the $top/portal-gui/README file to - set up the portal-gui for the self-hosted resource handle that runs - rpkid. - -- After running "make" in $top/portal-gui, there will be a file named - $top/portal-gui/apache/rpki.conf. This is a configuration file for - Apache which does most of the work configuring the portal-gui to - run under mod_wsgi. - -You may need to edit the paths for Django if they are installed in a -different location on your host. Note that this is only necessary if -you wish to use the Django admin web console. The portal-gui itself -will operate correctly even if this path is wrong. - -NOTE: Apache loads the configuration files sorted alphabetically. -Thus, you need to ensure that your file is renamed as appropriate for -your environment. - - Fedora: - $ cp $top/portal-gui/apache/rpki.conf /etc/httpd/conf.d/wsgi-rpki.conf - $ service httpd restart |