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
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
|
[[TracNav(doc/RPKI/TOC)]]
[[PageOutline]]
= Configuring the RPKI CA tools: `rpki.conf` =
This section describes `rpki.conf`, the the configuration file for the
RPKI CA tools.
The first subsection is a quick summary of the options you're most
likely to need to configure (or at least check) for a basic setup.
The rest of this section contains a more complete reference to the
configuration file and some of the things you might need to do with it
if your needs are more complex.
There are a lot of configuration options, but in most cases you will
never have to touch more than a few of them. Keep reading, and don't
panic.
== Quick guide to the most common configuration options ==
This subsection describes only a handful of `rpki.conf` configuration
options. These are the ones you'll need to set, or at least check, as
part of initial installation. In general, the installation process
will have already set sane values for these, but you may need to a few
of them depending on exactly what you're doing.
The location of `rpki.conf` varies depending on the operating system
you're running and how you installed the software. Unless you did
something unusual during installation, it's either `/etc/rpki.conf` or
`/usr/local/etc/rpki.conf`.
{{{
#!comment
Should we even discuss `handle` here? We no longer create any
ResourceHolderCA automatically, so it's almost irrelevant at this
point, and we'd like to get rid of it eventually. Leave it out for
now and see if anybody complains, I guess.
}}}
* All of the configuration options you're most likely to need to change
are in the `[myrpki]` section of `rpki.conf`.
{{{
#!ini
[myrpki]
}}}
* You need to check the setting of `rpkid_server_host`. The
installation process sets this to the fully-qualified DNS hostname
of the server on which you installed the code, but if you use a
service-specific DNS name for RPKI service you will need to change
this option to match that service name.
{{{
#!ini
rpkid_server_host = rpkid.example.org
}}}
* You need to set the value of `run_pubd` to reflect whether you
intend to run your own RPKI publication server and rsync server.
{{{
#!ini
run_pubd = yes
}}}
or
{{{
#!ini
run_pubd = no
}}}
* If you are running your own RPKI publication server, you need to
check the setting of `pubd_server_host`. The installation process
sets this to the fully-qualified DNS hostname of the server on which
you installed the code, but if you use a service-specific DNS name
for RPKI publication service you will need to change this option to
match that service name.
{{{
#!ini
pubd_server_host = pubd.example.org
}}}
There are //many// other configuration options, but setting the above
correctly should suffice to get you started with the default
configuration. Read on for details if you need to know more,
otherwise go to [[#nextsteps|next steps]].
== Configuration file syntax == #syntax
The general format of `rpki.conf` is the same as the configuration
language used by many other programs, including the OpenSSL package.
The file is divided into "sections", labeled with square brackets;
individual options within a section look like variable assignments,
with the option name on the left and the option value on the right.
{{{
#!ini
[foo]
bar = fred
baz = 42
}}}
The configuration file parser supports a limited version of the macro
facility used in OpenSSL's configuration parser. An expression such
as
{{{
#!ini
foo = ${bar::baz}
}}}
sets foo to the value of the baz variable from section
bar.
The section name `ENV` is special: it refers to environment variables.
{{{
#!ini
home = ${ENV::HOME}
}}}
Each of the programs that make up the RPKI tookit can potentially take
its own configuration file, but for most uses this is unnecessarily
complicated. The recommended approach is to use a single
configuration file, and to put all of the parameters that a normal
user might need to change into a single section of that configuration
file, then reference these common settings from the program-specific
sections of the configuration file via macro expansion.
The default name for the shared configuration file is `rpki.conf`.
The location of the system-wide `rpki.conf` file is selected by
`./configure` during installation. The default location is
`/usr/local/etc/rpki.conf` when building from source or on platforms
like FreeBSD or MacOSX where packaged software goes in the
`/usr/local` tree; on GNU/Linux platforms, binary packages will use
`/etc/rpki.conf` per GNU/Linux convention.
Regardless of the default location, you can override the build-time
default filename at runtime if necessary by setting the `RPKI_CONF`
environment variable to the name of the configuration file you want to
use. Most of the programs also take a command-line option (generally
"`-c`") specifying the name of the configuration file; if both the
command line option and the environment variable are set, the command
line option wins.
The installation process builds a sample configuration file
`rpki.conf.sample` and installs it alongside of `rpki.conf`. If you
have no `rpki.conf` installed, the installation process will copy
`rpki.conf.sample` to `rpki.conf`, but it will not overwrite an
existing `rpki.conf` file.
== Too much information about `rpki.conf` options ==
The list of options that you can set in `rpki.conf` is ridiculously
long. The default configuration includes what we hope are reasonable
default settings for all of them, so in many cases you will never need
to know about most of these options. A number of the options for
individual programs are specified in terms of other options, using the
macro facility [[#syntax|described above]].
In general, if you don't understand what an option does, you probably
should leave it alone.
Detailed information about individual options is listed in separate
sections, one per section of `rpki.conf`. These documentation
sections are generated from the same source file as the sample
configuration file.
{{{
#!comment
See notes in doc/RPKI/TOC about the format of link labels containing
square brackets like rpki.conf section names, and be careful here,
because the syntax is somewhat finicky.
}}}
* [[wiki:doc/RPKI/CA/Configuration/Common| Common Options ]]
* [[wiki:doc/RPKI/CA/Configuration/myrpki| [myrpki] section ]]
* [[wiki:doc/RPKI/CA/Configuration/rpkid| [rpkid] section ]]
* [[wiki:doc/RPKI/CA/Configuration/irdbd| [irdbd] section ]]
* [[wiki:doc/RPKI/CA/Configuration/pubd| [pubd] section ]]
* [[wiki:doc/RPKI/CA/Configuration/rootd| [rootd] section ]]
* [[wiki:doc/RPKI/CA/Configuration/web_portal| [web_portal] section ]]
* [[wiki:doc/RPKI/CA/Configuration/autoconf| [autoconf] section ]]
{{{
#!comment
Still have to write subsections linking to:
* [wiki:doc/RPKI/CA/Configuration/CreatingRoot Creating a RPKI Root Certificate]
* [wiki:doc/RPKI/CA/Configuration/Tests Test configuration]
* [wiki:doc/RPKI/CA/Configuration/DifferentServer Using Different Servers]
}}}
== rsyncd.conf ==
If you're running pubd, you'll also need to run rsyncd. Your rsyncd
configuration will need to match your pubd configuration in order for
relying parties to find the RPKI objects managed by pubd.
Here's a sample rsyncd.conf file:
{{{
#!ini
pid file = /var/run/rsyncd.pid
uid = nobody
gid = nobody
[rpki]
use chroot = no
read only = yes
transfer logging = yes
path = /some/where/publication
comment = RPKI publication
}}}
You may need to adapt this to your system. In particular, you will
need to set the `path` option to match the directory you named as
`publication_base_directory` in `rpki.conf`.
You may need to do something more complicated if you are already
running rsyncd for other purposes. See the `rsync(1)` and
`rsyncd.conf(5)` manual pages for more details.
== Running your own RPKI root ==
In general, we do not recommend running your own RPKI root
environment, for various reasons. If, however, you need to do so, you
should read
[[wiki:doc/RPKI/CA/Configuration/rootd| the documentation for the [rootd] section ]],
and
[[wiki:doc/RPKI/CA/Configuration/CreatingRoot| the instructions for creating a RPKI root certificate ]].
== Running rpkid or pubd on a different server ==
The default configuration runs rpkid, pubd (if enabled) and the back
end code all on the same server. For most purposes, this is fine, but
in some cases you might want to split these functions up among
different servers. If you need to do this, see
[wiki:doc/RPKI/CA/Configuration/DifferentServer these instructions].
== Configuring the test harness ==
We expect the test harness to be of interest primarily to developers,
but if you need to understand how it works, you will probably want to read
[wiki:doc/RPKI/CA/Configuration/Tests these instructions].
== Next steps == #nextsteps
Once you've finished with configuration, the next thing you should
read is the [[MySQLSetup|MySQL setup instructions]].
|
