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
|
$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.
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, csv files). 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/asns.csv
/usr/local/var/rpki/conf/Alice/bpki/
/usr/local/var/rpki/conf/Alice/entitydb/
/usr/local/var/rpki/conf/Alice/prefixes.csv
/usr/local/var/rpki/conf/Alice/roas.csv
/usr/local/var/rpki/conf/Alice/rpki.conf
/usr/local/var/rpki/conf/Bob/asns.csv
/usr/local/var/rpki/conf/Bob/bpki/
/usr/local/var/rpki/conf/Bob/entitydb/
/usr/local/var/rpki/conf/Bob/prefixes.csv
/usr/local/var/rpki/conf/Bob/roas.csv
/usr/local/var/rpki/conf/Bob/rpki.conf
/usr/local/var/rpki/conf/Carol/asns.csv
/usr/local/var/rpki/conf/Carol/bpki/
/usr/local/var/rpki/conf/Carol/entitydb/
/usr/local/var/rpki/conf/Carol/prefixes.csv
/usr/local/var/rpki/conf/Carol/roas.csv
/usr/local/var/rpki/conf/Carol/rpki.conf
=== 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.
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
=== rpkigui-list-resources helper script ===
The portal-gui does not directly talk to the rpkid server. Instead,
there is a command line script named "rpkigui-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. By default, this script is installed in
${libexecdir}, which is typically /usr/local/libexec.
NOTE that "rpkigui-list-resources" *MUST* be run in the directory
where the rpki.conf for the resource handle that is self-hosting the
rpkid. Alternatively, you can set the $RPKI_CONF environment
variable to full pathname of the rpki.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 rpki.conf.)
The first time you invoke it, you may wish to use the -v option, which
puts rpkigui-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:
/usr/local/libexec/rpkigui-list-resources -v
You may wish to create a script which is invoked by cron:
#!/bin/sh
# self-host resource handle
self_handle=FOO
# <directory containing rpki.conf for the self-hosted rpkid>
cd /usr/local/var/rpki/conf/$self_handle
/usr/local/libexec/rpkigui-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 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-list-resources" 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.
=== 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} (eg. /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").
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-list-resources"
step described above 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
=== 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.
Don't worry about losing data, because rpkigui-list-resources and
rpkigui-load-csv can be run again to populate the database with your
data.
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-list-resources -v
$ /usr/local/libexec/rpkigui-load-csv
|
