1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
$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 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 prefix. Defaults to /usr/local/.
--datarootdir=DIR
Install the portal-gui source code as $DIR/portal-gui.
Defaults to $prefix/share/.
--localstatedir=DIR
Set the default location for the portal-gui's database.
Defaults to $prefix/var/.
DATABASE_PATH=PATH
Specifies the full pathname for the sqlite database used to
back the portal gui. Defaults to
$localstatedir/portal-gui/rpkiop. NOTE: This path should
include the database filename, not only the directory
containing it.
--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.)
The first time you invoke it, you may wish to use the -v option, which puts
list_resources into verbose mode, meaning it will display progress
information. Normally, this script is intended to be invoked via cron, so
it is silent unless an error occurs:
$datarootdir/portal-gui/scripts/list_resources -v
You may way to create a script which is invoked by cron:
#!/bin/sh
cd <directory containing myrpki.conf for the self-hosted rpkid>
$datarootdir/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:
$datarootdir/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.
=== 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.
To create additional non administrative users:
- navigate to http://<ip:port>/admin/auth/user/
- click on the "Add User" link at the upper right
- fill in the username and password fields
- click "Save"
You can configure which users are allowed to manage a particular resource
handle once you have performed the "list_resources" step described above to
populate the database:
- navigate to http://<ip:port>/admin/myrpki/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
=== 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/myrpki/ 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. Don't worry about losing data,
because list_resources and load_csv can be run again to populate the
database with your data.
Here are the steps for reseting to the initial state:
cd $datarootdir/portal-gui/rpkigui
python manage.py reset --pythonpath=$top/rpkid myrpki
>>> answer "yes" to really reset it <<<
cd <directory containing myrpki.conf for the self-hosted rpkid>
$datarootdir/portal-gui/scripts/list_resources -v
$datarootdir/portal-gui/scripts/load_csv
|
