-
Notifications
You must be signed in to change notification settings - Fork 12
/
README.in
1096 lines (858 loc) · 42 KB
/
README.in
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
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
@PACKAGE_LONGNAME@
Installation and Usage Manual
Version @PACKAGE_VERSION@
===============================================================================
Table of Contents
1. Organization of this document
2. Installation
2.1 Prerequisites
2.1.0 Version Requirements
2.1.1 User Account
2.1.2 OpenSSL
2.1.3 MySQL and ODBC
2.1.4 cryptlib
2.1.5 rsync
2.1.6 Python
2.1.7 netcat
2.1.8 cURL
2.1.9 Syslog
2.2 @PACKAGE_NAME_UC@ Software
2.2.1 Unpack the Source Code
2.2.2 Configure
2.2.3 Build the Executables
2.3 @PACKAGE_NAME_UC@ User Account
2.3.1 Self-Test Configuration File
2.4 SSH Subsystem (optional)
2.5 Self Test
2.6 Installation
2.7 Post-Installation Procedures
2.8 Upgrade Procedure
2.9 Firewall
2.10 Run in Docker
3. Running the RPKI Software
3.1 Normal Operation
3.1.1 Note About Cron Jobs
3.1.2 @PACKAGE_NAME@-synchronize
3.1.3 @PACKAGE_NAME@-rpki-rtr-daemon
3.1.4 @PACKAGE_NAME@-rpki-rtr-update
3.2 Results and Analysis
3.2.1 Validation Report (@PACKAGE_NAME@-results)
3.2.2 Query Client (@PACKAGE_NAME@-query)
3.2.3 Log Files
3.3 Warning
Appendix A. Troubleshooting
A.1 Database troubleshooting
A.2 Specific Operating Systems
A.2.1 OpenBSD
A.2.2 FreeBSD
A.2.3 Ubuntu 12.04-12.10 x86
A.2.4 Mac OS X 10.8.5 (64-bit)
A.2.5 RHEL/CentOS 7 x86_64
A.3 Configure can't find installed software
===============================================================================
1. Organization of this document
This document describes how to install and use the Relying Party Security
Technology for Internet Routing (RPSTIR, pronounced rip-ster) software
by Raytheon BBN Technologies. Note that various files may refer to this
software by its old name, RPKI.
Section 2 describes how to install that software, including its dependencies.
Section 3 provides a quick-start guide on how to get your system running.
Appendix A provides troubleshooting tips for some common problems.
===============================================================================
2. Installation
The RPKI software is distributed as source code that should be built
using the GNU build tools on Linux/Unix. After reading this section,
you will know:
. How to install and configure the prerequisites.
. How to build the @PACKAGE_NAME@ software.
. How to set up a user with the correct environment.
. How to validate the installation.
We assume that you can operate your system's package manager, as well
as build packages from source and do minor edits on Makefiles.
2.1 Prerequisites
When installing prerequisites from your operating system's package
manager, you may need to look for a -dev or -devel version of each
package. These versions generally contain header files that are needed
to build @PACKAGE_NAME@.
2.1.0 Version Requirements
OpenSSL (Section 2.1.2) at least @MIN_OPENSSL_VERSION@
MySQL (Section 2.1.3) at least @MIN_MYSQL_VERSION@
ODBC mySql Connector (Section 2.1.3) at least @MIN_MYSQL_ODBC_VERSION@
rsync (Section 2.1.5) at least @MIN_RSYNC_VERSION@
Python (Section 2.1.6) at least @MIN_PYTHON_VERSION@
patch (Section 2.5)
2.1.1 User Account
You must establish a user account from which you can build and run @PACKAGE_NAME@.
While the full environment setup is detailed in section 2.3, the basic user
should be created now so that you can set and test environment variables. It
is not necessary, but recommended that the user is the only user in their
primary group.
For the rest of this document, commands starting with `$' should be run as
this user and commands starting with `#' should be run as root. If neither is
specified, the command should be run as @PACKAGE_NAME@'s user.
2.1.2 OpenSSL
You must build OpenSSL from source in order to enable support for
RFC3779 X.509v3 extensions. Download the latest source code (at least
version @MIN_OPENSSL_VERSION@) from http://www.openssl.org. We recommend the default
installation target directory /usr/local/ssl. As of version 1.0.1e,
the steps were:
$ ./config shared enable-rfc3779
$ make depend
$ make
$ make test
# make install
In addition, some scripts invoke the OpenSSL executable from the
shell. Modify your user's PATH such that `which openssl` points to
the custom-compiled binary that supports RFC 3779 extensions. This can
typically be done by adding a line like the below to the user's ~/.bashrc
file or another file that's automatically loaded by the shell.
export PATH="/usr/local/ssl/bin:$PATH"
2.1.3 MySQL and ODBC
Install unixODBC from your operating system's package manager or
http://www.unixodbc.org/. iODBC is also supported, but unixodbc is
recommended. Install the MySQL database server, client, and client
libraries, at least version @MIN_MYSQL_VERSION@, from the package manager or
http://mysql.org. Install the MySQL Connector/ODBC driver, at least
version @MIN_MYSQL_ODBC_VERSION@, from the package manager or mysql.org.
Configure MySQL. First, secure the initial MySQL accounts, which
includes setting a root password (see MySQL 5.1 manual, section
2.13.2). Then set up a database user and database(s) for @PACKAGE_NAME@.
If you want to run the self-tests, it is recommended to create a separate
database for testing than for production use. If you don't want to run the
self-tests, only one database is needed. For example, the following creates
a root password, then sets up a user with username "@PACKAGE_NAME@", password "bbn",
and access to the databases named "@PACKAGE_NAME@" and "@PACKAGE_NAME@_test":
$ mysql -u root
mysql> SELECT Host, User FROM mysql.user; /* view all accounts */
mysql> SET PASSWORD FOR 'root'@'127.0.0.1' = PASSWORD('rootpass');
mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('rootpass');
mysql> SET PASSWORD FOR 'root'@'<myhostname>' = PASSWORD('rootpass');
mysql> CREATE USER '@PACKAGE_NAME@'@'localhost' IDENTIFIED BY 'bbn';
mysql> CREATE DATABASE @PACKAGE_NAME@;
mysql> GRANT ALL PRIVILEGES ON @PACKAGE_NAME@.* TO '@PACKAGE_NAME@'@'localhost';
mysql> CREATE DATABASE @PACKAGE_NAME@_test;
mysql> GRANT ALL PRIVILEGES ON @PACKAGE_NAME@_test.* TO '@PACKAGE_NAME@'@'localhost';
Configure the Connector/ODBC driver. First, locate your system ODBC
drivers and data sources configuration files. For example:
$ odbcinst -j
unixODBC 2.2.11
DRIVERS............: /usr/local/etc/odbcinst.ini
SYSTEM DATA SOURCES: /usr/local/etc/odbc.ini
USER DATA SOURCES..: /home/achi/.odbc.ini
Some systems provide example odbcinst.ini files. For example, Ubuntu's
libmyodbc package provides /usr/share/libmyodbc/odbcinst.ini. If your system
provides a suitable file, use it to fill in odbcinst.ini. Otherwise, you can
use this as an example starting point for odbcinst.ini:
-----------------------------------------------------------------------------
; Sample /usr/local/etc/odbcinst.ini
[myodbcConn]
Description = MySQL odbc driver for Linux & Win32
Driver = /usr/local/lib/libmyodbc3.so ; could also be called libmyodbc.so
Setup = /usr/local/lib/libmyodbc3S.so ; could also be called libmyodbcS.so or libodbcmyS.so
UsageCount = 1
[ODBC]
TraceFile = /tmp/sql-odbc.log
Trace = Yes
ForceTrace = Yes
-----------------------------------------------------------------------------
Then edit odbc.ini to set up a couple of system data sources. This is
slightly confusing: the user, password, and database name are actually
ignored because they will be overridden by @PACKAGE_NAME@. However,
depending on whether your database user has a password, in future steps
below you will need to remember to set your DatabaseDSN configuration
option to choose the DSN that is expecting a password (e.g. "myodbc")
or no password (e.g. "myodbc-np"). Here is an example of a working
odbc.ini that corresponds to the odbcinst.ini above:
-----------------------------------------------------------------------------
;
; odbc.ini configuration for Connector/ODBC and Connector/ODBC 3.51 drivers
; /usr/local/etc/odbc.ini
;
[ODBC Data Sources]
myodbc = {MyODBC 3.51 Driver DSN}
myodbc-np = {MyODBC 3.51 Driver DSN for users without password}
[myodbc]
Driver = myodbcConn
Description = Connector/ODBC 3.51 Driver DSN
SERVER = localhost
PORT =
USER = arbitraryuser
Password = arbitrarypassword
Database = arbitrarydbname
OPTION = 3
SOCKET =
[myodbc-np]
Driver = myodbcConn
Description = Connector/ODBC 3.51 Driver DSN
SERVER = localhost
PORT =
USER = arbitraryuser
; Password = thisiscommentedout
Database = arbitrarydbname
OPTION = 3
SOCKET =
-----------------------------------------------------------------------------
You may also choose to set up user-specific $HOME/.odbc.ini file if
you need special DSN settings per user. However, this is not required
for successful operation of the RPKI software.
2.1.4 cryptlib
Install Peter Gutmann's cryptlib, currently available at
http://www.cs.auckland.ac.nz/~pgut001/cryptlib. When compiling on *nix, it
may be necessary to unzip in text mode to ensure that line endings are
correct. Ensure that both the library itself and its include files are in
accessible locations. For example, it may be necessary to manually copy
libcl.so to /usr/local/lib and cryptlib.h to /usr/local/include. To install
cryptlib 3.4.2 (for example):
$ wget --passive ftp://ftp.franken.de/pub/crypt/cryptlib/cl342.zip
$ mkdir cryptlib
$ cd cryptlib
$ unzip -a ../cl342.zip # -a enables text-mode
$ make shared # create libcl.so, not libcl.a
$ su
# install -o root -g root -m 755 libcl.so.3.4.2 /usr/local/lib
# ln -s libcl.so.3.4.2 /usr/local/lib/libcl.so
# install -o root -g root -m 644 cryptlib.h /usr/local/include
On FreeBSD, cryptlib can be obtained one of two ways: (1) using the package
system by issuing the command pkg_add -r cryptlib, or (2) using the ports
system by issuing the command make search name="cryptlib" from the
/usr/ports directory.
There seem to be some problems with compiling cryptlib on Linux machines.
You may need to modify some files to get it to build cleanly. Also note that
the self-test code (make testlib; ./testlib) fails on at least FreeBSD
and Linux. We do not currently think that this is cause for concern.
2.1.5 rsync
Your rsync should be at least version @MIN_RSYNC_VERSION@, as earlier versions do
not necessarily support the necessary flags. Check your version with
rsync --version, and install from rsync.samba.org. We recommend the
latest version due to security and bug fixes.
2.1.6 Python
Install python, at least version @MIN_PYTHON_VERSION@. Python is likely available in
your operating system's package manager and is also available at
http://python.org/download/.
2.1.7 netcat
Netcat comes preinstalled with many operating systems. If you do not
already have the command nc, install netcat from your package manager
or http://netcat.sourceforge.net/.
2.1.8 cURL
cURL also comes preinstalled with many operating systems. If the command
curl is not already present, install it from your package manager or
http://curl.haxx.se/.
2.1.9 Syslog
A syslog daemon is almost definitely already installed. However, on some
systems syslog has poor performance by default. See
http://stackoverflow.com/questions/208098/can-syslog-performance-be-improved
for more information. If you're ok with the chance of losing some log messages
if the system crashes, consider configuring your syslog daemon to not
synchronize log files after each log message.
2.2 @PACKAGE_NAME_UC@ Software
@PACKAGE_NAME_UC@ is distributed as source code that should be built
using the GNU build tools on Linux/Unix.
2.2.1 Unpack the Source Code
@PACKAGE_NAME_UC@ will have been delivered to you as a gzip-ed tarball
named @PACKAGE_TARNAME@-@[email protected]. Extract the file using:
$ tar xvzpf @PACKAGE_TARNAME@-@[email protected]
This will create a directory named @PACKAGE_TARNAME@-@PACKAGE_VERSION@ which
will contain various subdirectories.
Alternatively, you can get @PACKAGE_NAME@ from git if you want the latest version
(which may or may not be particularly stable). In addition to the above
prerequisites, you'll need to install git (http://git-scm.com/), automake
(http://www.gnu.org/software/automake/), and autoconf
(http://www.gnu.org/software/autoconf/). Then run the below commands:
$ git clone https://github.com/bgpsecurity/rpstir.git
$ cd rpstir
$ ./autogen.sh
2.2.2 Configure
@PACKAGE_NAME_UC@ uses autoconf to generate its Makefiles. On many systems,
it will suffice to run ./configure. However, the following options may be
useful.
Optional Packages:
--with-PACKAGE[=ARG] use PACKAGE [ARG=yes]
--without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no)
--with-ssl-include Path to openssl library install location: Defaults
to /usr/local/ssl/include
--with-ssl-lib Path to openssl library install location: Defaults
to /usr/local/ssl/lib
--with-cryptlib-include Path to cryptlib install location: Defaults to
/usr/local/include
--with-odbc-include Path to unixodbc include files: Defaults to
/usr/local/include
--with-cryptlib-lib Path to cryptlib install location: Defaults to
/usr/local/lib
--with-odbc-lib Path to unixODBC install location: Defaults to
/usr/local/lib
In addition, GNU make has the ability to dramatically reduce its
output. If you are using GNU make, then you have the option to use
$ ./configure --enable-silent-rules [other options]
which will give much shorter compilation/linking notifications.
The rpki-rtr code currently only compiles under gcc. If you have multiple
compilers installed, add the option "CC=gcc" to ./configure.
2.2.3 Build the Executables
Once the configure script has generated all of the Makefiles, build
the executables by issuing "make" in the top-level source directory.
2.3 @PACKAGE_NAME_UC@ User Account
Establish a user account from which to run @PACKAGE_NAME@. This
provides a place to put the configuration file and prevent other users
from reading sensitive information in it. It also provides a place,
~/.ssh/authorized_keys, to put all the RPKI-RTR clients' public keys to
allow SSH login.
If you're installing to a non-standard location, add the bin directoy to the
user's $PATH.
2.3.1 Self-Test Configuration File
@PACKAGE_NAME_UC@ uses two different configuration files, one for normal
operations and one for the self tests. This step sets up the configuration
file for the self-tests only. If you don't plan to run the self-tests, you
can skip this section.
Copy etc/test.conf to ~/.@[email protected] and make it readable only by
the owner because it will contain a database password:
$ cp etc/test.conf ~/.@[email protected]
$ chmod 600 ~/.@[email protected]
Open ~/.@[email protected] in an editor, read the comments, and edit the
file as directed by the comments.
NOTE: This file has database options that are homologous to options in the
system-wide configuration file that you'll set up later. If you use the same
database in both files, the self-tests will overwrite any data you keep in
your production database. It is strongly recommended to use a different
database for testing than for production use.
2.4 SSH Subsystem (optional)
If you plan to use the rpki-rtr server as an SSH subsystem, you will need
to run @PACKAGE_NAME@-rpki-rtr-daemon and set up an ssh subsystem
to connect to rtrd on localhost. The netcat program, nc(1), is
recommended for the ssh subsystem. There are different versions of
netcat, so read its manpage for caveats before setting it up as
a subsystem. In particular, read the "-q" option's description, if your
version of netcat has a "-q" option, to prevent runaway nc processes
when clients disconnect. Edit the /etc/ssh/sshd_config file to contain
the below line, modified for the options you want to pass to netcat:
Subsystem rpki-rtr nc <nc-options>... localhost <rtr-port>
2.5 Self Test
If you didn't create the configuration files in step 2.3.1, go back and do that
now. Some of the self tests won't work without the test configuration file.
It's necessary to create the VRS cache directory before run the self-test.
# mkdir -p \
/usr/local/var/cache/@PACKAGE_NAME@-tmp
# chown @PACKAGE_NAME@:@PACKAGE_NAME@ \
/usr/local/var/cache/@PACKAGE_NAME@-tmp
# chmod 700 \
/usr/local/var/cache/@PACKAGE_NAME@-tmp
To perform a basic validation of your install, run the self-test target by
issuing the command below. The self-tests do not support concurrent operation,
so do not try to run make with more than one simultaneous job (i.e., do not pass
the -jN option to make).
$ make check
If all tests pass, you will see a message indicating success.
If you have valgrind installed, you can run some tests under valgrind
by running the command:
$ make check CHECKTOOL=valgrind
2.6 Installation
As root, run "make install" to install @PACKAGE_NAME@ on the system.
# make install
By default this will install various binaries to /usr/local/bin, which should
be in the $PATH environment variable. Additional binaries, which should only
be used internally or by experts, are in /usr/local/libexec/@PACKAGE_NAME@.
Documentation, example configuration, and example trust anchor locators are
installed in /usr/local/share/doc/@PACKAGE_NAME@. Some internal data is
installed to /usr/local/share/@PACKAGE_NAME@. In the next step, you'll manually
create cache and log directories.
2.7 Post-Installation Procedures
If this is the first time you've installed @PACKAGE_NAME@ (i.e. if this is not
an upgrade), there are some initialization steps.
First, create the system-wide configuration directory and file. The
system-wide configuration directory is /usr/local/etc/@PACKAGE_NAME@ by default.
If you changed the value of ${sysconfdir}, use ${sysconfdir}/@PACKAGE_NAME@
instead. Files in the configuration directory should be readable only by the
@PACKAGE_NAME@ user and root. After creating the directory, create a file
@[email protected] in it. There's a sample file that's in
/usr/local/share/doc/@PACKAGE_NAME@/examples/@[email protected] by default that you can use as
a starting point. Assuming everything is in default locations and the user you
created in step 2.1.1 is @PACKAGE_NAME@ with group @PACKAGE_NAME@:
# mkdir /usr/local/etc/@PACKAGE_NAME@
# cp /usr/local/share/doc/@PACKAGE_NAME@/examples/@[email protected] /usr/local/etc/@PACKAGE_NAME@/
# chown root:@PACKAGE_NAME@ /usr/local/etc/@PACKAGE_NAME@ /usr/local/etc/@PACKAGE_NAME@/@[email protected]
# chmod 750 /usr/local/etc/@PACKAGE_NAME@
# chmod 640 /usr/local/etc/@PACKAGE_NAME@/@[email protected]
Then open the configuration file you just created in an editor, read the
comments, and edit the file as directed by the comments.
# vi /usr/local/etc/@PACKAGE_NAME@/@[email protected]
Later on, if you want to test configuration changes before changing the
system-wide configuration, you can make a new configuration file and use it
temporarily by setting $@CONFIG_ENV_VAR@, for example:
$ @CONFIG_ENV_VAR@=path/to/foo.conf path/to/executable
In the configuration file you just created, find the parameters RPKICacheDir
and LogDir. Both of these directories, and ${localstatedir}/lib/@PACKAGE_NAME@,
should be created and the user from step 2.1.1 should have full access to these
directories. For example, if the directories are set to their defaults and the
username is @PACKAGE_NAME@ in group @PACKAGE_NAME@:
# mkdir -p \
/usr/local/var/cache/@PACKAGE_NAME@ \
/usr/local/var/lib/@PACKAGE_NAME@ \
/usr/local/var/log/@PACKAGE_NAME@
# chown @PACKAGE_NAME@:@PACKAGE_NAME@ \
/usr/local/var/cache/@PACKAGE_NAME@ \
/usr/local/var/lib/@PACKAGE_NAME@ \
/usr/local/var/log/@PACKAGE_NAME@
# chmod 700 \
/usr/local/var/cache/@PACKAGE_NAME@ \
/usr/local/var/lib/@PACKAGE_NAME@ \
/usr/local/var/log/@PACKAGE_NAME@
Then run @PACKAGE_NAME@-initialize to set up the database:
$ @PACKAGE_NAME@-initialize -f # WARNING: This will delete any old data you
# have in the configured database.
# Do not do this if you're upgrading
# and want to save your old data.
2.8 Upgrading
Consider backing up your configuration and data before upgrading @PACKAGE_NAME@.
To upgrade @PACKAGE_NAME@, first upgrade the dependencies to the versions in
section 2.1.0. Then compile (section 2.2) and install (section 2.6) @PACKAGE_NAME@.
Run @PACKAGE_NAME@-upgrade with the version number of the previous release. For
example, to upgrade from version 0.7, run:
$ @PACKAGE_NAME@-upgrade 0.7
2.9 Firewall
As part of @PACKAGE_NAME@'s normal operation, it fetches RPKI objects over rsync.
Many of these objects contain links to additional RPKI objects, which @PACKAGE_NAME@
then attempts to fetch, recursively. If you plan to make the results of @PACKAGE_NAME@'s
validation public and if your local network (or localhost) contains any
confidential data available over rsync, you may want to set up a firewall to
prevent @PACKAGE_NAME@ from downloading any data it shouldn't.
2.10 Run in Docker
The @PACKAGE_NAME@ can run in Docker, please refer to the handbook in doc/docker/Install_and_Run_Rpstir_in_Docker.txt
===============================================================================
3. Running the RPKI Software
3.1 Normal Operation
This section describes when and how to run each component of @PACKAGE_NAME@ as
part of a relying party's normal operations. Cron jobs and init scripts are
not included in this release, but this section should give the user enough
information to create cron jobs or init scripts as appropriate.
3.1.1 Note About Cron Jobs
If you create cron jobs for @PACKAGE_NAME@, it is strongly recommended that you
pick random numbers for the fixed parts of the cron job. For example, if you
want to run @PACKAGE_NAME@ once per hour, pick a random number between 0 and 59
to use as the minute that @PACKAGE_NAME@ runs on every hour. Likewise, if you
want to run once per day, pick a random minute between 0 and 59 and a random
hour between 0 and 23. This should help spread out the load on the public
RPKI servers.
3.1.2 @PACKAGE_NAME@-synchronize
@PACKAGE_NAME@-synchronize synchronizes the local cache with the global RPKI,
or anything else pointed to by the configured trust anchor locators. It should
be run regularly, for example by a cron job. The amount of time it takes to
complete one run can vary, so experimentation is suggested before picking the
frequency to run it.
3.1.3 @PACKAGE_NAME@-rpki-rtr-daemon
@PACKAGE_NAME@-rpki-rtr-daemon is @PACKAGE_NAME@'s rpki-rtr [rfc6810]
server. If you plan to run an rpki-rtr server, this should be started on boot,
e.g. from an init script or from rc.local. This program does not daemonize, but
something like start-stop-daemon can be used.
3.1.4 @PACKAGE_NAME@-rpki-rtr-update
After @PACKAGE_NAME@-synchronize finishes, @PACKAGE_NAME@-rpki-rtr-update can
update the rpki-rtr cache. If you plan to use the rpki-rtr server, you should
call @PACKAGE_NAME@-rpki-rtr-update after each successful call to
@PACKAGE_NAME@-synchronize. For example, the cron job command could be:
@PACKAGE_NAME@-synchronize && @PACKAGE_NAME@-rpki-rtr-update
3.2 Results and Analysis
This section describes some of your options for getting more information about
@PACKAGE_NAME@'s operations (see previous section) or the state of the RPKI.
3.2.1 Validation Report (@PACKAGE_NAME@-results)
If you want an overview of @PACKAGE_NAME@'s cached view of the RPKI, you can
use
@PACKAGE_NAME@-results
This should have some non-zero values for the validated objects if the
@PACKAGE_NAME@-synchronize ran successfully.
At a basic level, every object is in one of three states: fully
validated to a trust anchor, unknown, and definitely invalid. Valid
objects are inserted in the database; unknown objects are potentially
valid, so they are kept in the database; definitely invalid objects
are not entered into the database.
The validation report generator (@PACKAGE_NAME@-results) searches the local cache
and the database and summarizes the three categories as counts. In
verbose mode, it also shows full paths to all invalid/unknown
certifcates, thereby allowing the user to determine the offending
rsync publication URI.
To see a list of options, run
$ @PACKAGE_NAME@-results --help
3.2.2 Query Client (@PACKAGE_NAME@-query)
This is the way to pull specific information out of the database and
local repository. There are two basic modes.
The comprehensive query, indicated by the argument "-r", pulls all the
valid ROAs from the repository and outputs a set of BGP filters in
RPSL format specified by these ROAs. To send the output to a file
rather than the screen, include "-o <filename>" on the command line or
just redirect the output. ROAs (as well as certificates and CRLs) can
also be stale for a variety of reasons:
- Validation Chain Stale: The ROA was validatated by a trust chain
at some point, but now there is no longer a trust chain (e.g., due
to a certificate expiring or being revoked by a CRL).
- Stale CRL: Some certificate in the ROA's trust chain is in the
domain of a CRL that was supposed to be updated by a certain time
and has not.
- Stale Manifest: Similar to stale CRL
- No Manifest: Either the ROA or some certificate in its trust chain
is not on a validated manifest.
For each type of staleness, it is possible to specify that the query
consider ROAs that are stale in this manner to be either all valid or
all invalid. To control how different types of staleness are treated,
edit the config file created in step 2.3.1.
The informational query provides the user with a means to see what is
in the database without directly executing MySQL commands. The basic
informational query has the form
@PACKAGE_NAME@-query -t <type> -d <field> [-d <field> ... -d <field>]
where type is either cert, crl, roa or manifest, and the fields are
all the fields of the objects to display. There are different
possible fields for each object type. The full list of possibilities
is obtained with the command "@PACKAGE_NAME@-query -l <type>". Most of these
fields also provide the capability for filtering the results based on
a simple comparison. To do such filtering, add as many "-f
<field>.<op>.<value>" arguments to the command line as desired, where
op is one of (eq, ne, lt, gt, le, ge) and value is unquoted and
contains # characters to replaces spaces. Additional arguments are
given if you type @PACKAGE_NAME@-query without any arguments.
Examples:
$ @PACKAGE_NAME@-query -t cert -d pathname # display paths of valid certs
$ @PACKAGE_NAME@-query -t cert -d pathname -d flags # display path+flags of valid certs
$ @PACKAGE_NAME@-query -t cert -d pathname -i # display paths of valid/unknown certs
$ @PACKAGE_NAME@-query -t crl -d all # display all fields of valid CRLs
$ @PACKAGE_NAME@-query -t roa -d pathname -d flags # display path+flags of valid roas
$ @PACKAGE_NAME@-query -t man -d all -i # display all fields of valid/unknown manifests
$ @PACKAGE_NAME@-query -t man -d all -f filename.eq.foo.mft # find all manifests named "foo.mft"
3.2.3 Log Files
@PACKAGE_NAME_UC@ logs most things to syslog, so you can check your system logs
for more information. These are most likely in /var/log/syslog,
/var/log/messages, or another file in /var/log. There are also some additional
logs (e.g., rsync's logs) in the directory specified by the LogDir configuration
parameter, which is /usr/local/var/log/@PACKAGE_NAME@ by default.
3.3 Warning
Aborting any of the scripts that change the database or repository in
the middle of operation can leave the database in an inconsistent
state. It is recommended that after any such abort, you re-initialize
the database, clear the repository, and reload the data from scratch.
In the future, we plan to provide less drastic means of recovering
from an abort.
===============================================================================
Appendix A. Troubleshooting
A.1 Database troubleshooting
If you are having database errors, particularly when you first attempt
to use rcli, it is important to check and make sure that your MySQL
installation is correct. Try the following command (drop the '-p' if
your MySQL user has no password):
$ mysql --user=YOUR_DB_USER -p
This should connect you to the database and give a "mysql> " prompt
back. If it does not, then your MySQL and/or ODBC installation is not
correct. Check the troubleshooting section of the MySQL
documentation. Verify that your ODBC information, in
/usr/local/etc/odbc.ini and /usr/local/etc/odbcinst.ini, is correct.
Verify that the MySQL daemon process mysqld is running using "ps -ef".
Verify that there is a mysql socket named mysql.sock, typically in
/tmp.
Once you can successfully connect to the database as user "mysql" try
connecting as root by issuing the command:
$ mysql --user=root --password=PWD
where PWD is the root password specified in your odbc.ini file. If
this does not succeed, follow the steps given in the MySQL manual for
resetting the root password, then stop and restart the mysqld process.
A.2 Specific Operating Systems
A.2.1 OpenBSD
If you have trouble compiling mysql-ODBC-connector, you may need to find
all lines in its source that call wprintf() or swprintf() and comment
them out.
A.2.2 FreeBSD
If you have trouble compiling cryptlib, you may have to comment out the
sections in tools/ccopts.sh that enable ODBC support.
A.2.3 Ubuntu 12.04-13.04 x86
These are the exact instructions for installing RPSTIR on a fresh copy
of 32-bit Ubuntu 12.04, 12.10 and 13.04, as of June 7, 2013.
NOTE: Ubuntu 12.10 runs slowly without 3D acceleration due to the
removal of Unity 2D. In VirtualBox 4.2.4, fix it like so:
http://askubuntu.com/questions/207813/why-does-an-ubuntu-12-10-guest-in-virtualbox-run-very-very-slowly
The last check step may crash VirtualBox itself (yikes). Don't run
the final "/usr/lib/nux/unity_support_test -p"
# Install the best editor :-)
sudo apt-get install emacs
# Build tools
sudo apt-get install openjdk-7-jdk build-essential
# RPSTIR dependencies: standalone programs
sudo apt-get install curl
sudo apt-get install unzip
sudo apt-get install mysql-server # MySQL root password: rpstir
sudo mysql_secure_installation
# RPSTIR dependencies: libraries
sudo apt-get install unixodbc-bin unixodbc-dev libmyodbc libmysqlclient-dev
mkdir -p ~/libs
# OpenSSL w/ RFC3779 extensions
cd ~/libs
curl -OJ http://www.openssl.org/source/openssl-1.0.1e.tar.gz
tar -xzvf openssl-1.0.1e.tar.gz
cd openssl-1.0.1e/
./config enable-rfc3779 && make depend && make && make test
sudo make install
# Cryptlib
cd ~/libs
curl -OJ ftp://ftp.franken.de/pub/crypt/cryptlib/cl342.zip
mkdir cryptlib
cd cryptlib
unzip -a ../cl342.zip # -a enables text-mode
make shared # create libcl.so, not libcl.a
sudo install -o root -g root -m 755 libcl.so.3.4.2 /usr/local/lib
sudo ln -s libcl.so.3.4.2 /usr/local/lib/libcl.so
sudo install -o root -g root -m 644 cryptlib.h /usr/local/include
# Configure ODBC
odbcinst -j # check that the paths below are correct
# populate driver file
sudo emacs /etc/odbcinst.ini
; ODBC Installed Drivers file
[myodbcConn]
Description = MySQL odbc driver for Linux
Driver = /usr/lib/i386-linux-gnu/odbc/libmyodbc.so
Setup = /usr/lib/i386-linux-gnu/odbc/libodbcmyS.so
UsageCount = 1
[ODBC]
TraceFile = /tmp/sql-odbc.log
Trace = Yes
ForceTrace = Yes
# populate user data sources
emacs ~/.odbc.ini
;
; odbc.ini configuration for Connector/ODBC drivers
;
[ODBC Data Sources]
myodbc = {MyODBC Driver DSN}
[myodbc]
Driver = myodbcConn
Description = Connector/ODBC Driver DSN
SERVER = localhost
PORT =
USER = arbitraryuser
Password = arbitrarypassword
Database = arbitrarydbname
OPTION = 3
SOCKET =
# Configure MySQL
mysql -u root -p
CREATE USER 'rpstir'@'localhost' IDENTIFIED BY 'bbn';
CREATE DATABASE rpstir;
GRANT ALL PRIVILEGES ON rpstir.* TO 'rpstir'@'localhost';
CREATE DATABASE rpstir_test;
GRANT ALL PRIVILEGES ON rpstir_test.* TO 'rpstir'@'localhost';
quit
# Configure, build, test, and install rpstir
cd path/to/rpstir # the directory this file is in
./configure --enable-silent-rules
make
cp etc/test.conf ~/.rpstir.test.conf
chmod 600 ~/.rpstir.test.conf
emacs ~/.rpstir.test.conf # set these options:
Database rpstir_test
DatabaseUser rpstir
DatabasePassword bbn
make check
sudo make install
# Setup rpstir
sudo mkdir /usr/local/etc/rpstir
sudo cp /usr/local/share/doc/rpstir/examples/rpstir.conf /usr/local/etc/rpstir/
sudo chown root:rpstir /usr/local/etc/rpstir /usr/local/etc/rpstir/rpstir.conf
sudo chmod 750 /usr/local/etc/rpstir
sudo chmod 640 /usr/local/etc/rpstir/rpstir.conf
sudoedit /usr/local/etc/rpstir/rpstir.conf # read the comments for each option, and make sure to set these:
Database rpstir
DatabaseUser rpstir
DatabasePassword bbn
sudo mkdir -p /usr/local/var/cache/rpstir /usr/local/var/log/rpstir
sudo chown rpstir:rpstir /usr/local/var/cache/rpstir /usr/local/var/log/rpstir # substitute rpstir:rpstir with your username and group
sudo chmod 700 /usr/local/var/cache/rpstir /usr/local/var/log/rpstir
rpstir-initialize -f # if this is not a fresh install, THIS STEP WILL ERASE RPSTIR'S OLD DATA
A.2.4 Mac OS X 10.8.5 (64-bit)
These are the exact instructions for installing rpstir on a fresh copy of Mac OS
X 10.8.5 (64-bit), as of January 2, 2014. Note that rpstir is not tested on Mac
as much as on other platforms. Additionally, the rpki-rtr daemon is susceptible
to a denial of service by local users, so do not run rpstir on a shared Mac
system. RPSTIR has only been tested running in 32-bit mode on Mac, so the
instructions below build various ports with the +universal flag, and rpstir
itself is built for i386.
First, install Mac Ports from http://www.macports.org/. This requires an Apple
ID to download Xcode. Make sure to also install the Xcode Command Line Tools.
# Make sure that +universal will cause ports to be built for i386. Edit the file
# below and find the line that sets universal_archs. It must include i386.
sudo vim /opt/local/etc/macports/macports.conf
# Run the below commands if you're getting rpstir from git instead of from a
# tarball.
sudo port install git-core
sudo port install automake
sudo port install autoconf
# Install rpstir's dependencies.
sudo port install openssl +rfc3779 +universal
sudo port install cryptlib +universal
sudo port install mysql5 +universal
sudo port install mysql5-server
sudo port install unixODBC +universal
sudo port install mysql-connector-odbc build_arch=i386 # NOTE: this uses build_arch=i386 instead of +universal because of https://trac.macports.org/ticket/41755
# Configure MySQL
export PATH="/opt/local/lib/mysql5/bin:$PATH" # Consider adding this to your shell's startup file too.
sudo -u _mysql mysql_install_db5
sudo port load mysql5
mysql_secure_installation5 # MySQL root password: rpstir
mysql5 -u root -p
CREATE USER 'rpstir'@'localhost' IDENTIFIED BY 'bbn';
CREATE DATABASE rpstir;
GRANT ALL PRIVILEGES ON rpstir.* TO 'rpstir'@'localhost';
CREATE DATABASE rpstir_test;
GRANT ALL PRIVILEGES ON rpstir_test.* TO 'rpstir'@'localhost';
quit
# Configure ODBC
sudo vim /opt/local/etc/odbcinst.ini
[MySQL]
Description = ODBC for MySQL
Driver = /opt/local/lib/libmyodbc5.so
sudo vim /opt/local/etc/odbc.ini
[myodbc]
Description = myodbc
Driver = MySQL
Server = localhost
Port =
User = arbitraryuser
Password = arbitrarypassword
Database = arbitrarydbname
# Configure, build, test, and install rpstir
cd path/to/rpstir # the directory this file is in
./autogen.sh # Only do this if running from git instead of from a tarball
./configure --with-cryptlib-include=/opt/local/include --with-cryptlib-lib=/opt/local/lib CFLAGS="-arch i386" LDFLAGS="-arch i386"
make
cp etc/test.conf ~/.rpstir.test.conf
chmod 600 ~/.rpstir.test.conf
vim ~/.rpstir.test.conf # set these options:
Database rpstir_test
DatabaseUser rpstir
DatabasePassword bbn
make check # There's one test that does not work yet on Mac: tests/conformance/scripts/run_tests.tap
sudo make install
# Setup rpstir
sudo mkdir -p /usr/local/etc/rpstir
sudo cp /usr/local/share/doc/rpstir/examples/rpstir.conf /usr/local/etc/rpstir/
sudo chown root:rpstir /usr/local/etc/rpstir /usr/local/etc/rpstir/rpstir.conf # substitute 'rpstir' in 'root:rpstir' for the group of the user you plan to run rpstir as
sudo chmod 750 /usr/local/etc/rpstir
sudo chmod 640 /usr/local/etc/rpstir/rpstir.conf
sudo vim /usr/local/etc/rpstir/rpstir.conf # read the comments for each option, and make sure to set these:
Database rpstir
DatabaseUser rpstir
DatabasePassword bbn
sudo mkdir -p /usr/local/var/cache/rpstir /usr/local/var/log/rpstir
sudo chown rpstir:rpstir /usr/local/var/cache/rpstir /usr/local/var/log/rpstir # substitute rpstir:rpstir with your username and group
sudo chmod 700 /usr/local/var/cache/rpstir /usr/local/var/log/rpstir
rpstir-initialize -f # if this is not a fresh install, THIS STEP WILL ERASE RPSTIR'S OLD DATA
A.2.5 RHEL/CentOS 7 x86_64
These are the exact instructions for installing RPSTIR on a fresh copy
of 64-bit CentOS 7 (as of July 2016)
# Build tools
sudo yum install libtool autoconf automake gcc patch
# RPSTIR dependencies: standalone programs
sudo yum install curl nc unzip python rsync
# editor of choice
sudo yum install emacs-nox vim-enhanced
# MySQL
sudo yum install mariadb mariadb-server
# Set up MySQL root password: rpstir
sudo mysql_secure_installation
# RPSTIR dependencies: libraries
sudo yum install mariadb-libs mariadb-devel unixODBC unixODBC-devel \
mysql-connector-odbc openssl-devel
There are two options for Cryptlib. The easiest is to install it from the
EPEL repository.
sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo yum install cryptlib-devel
If you dont want to or cant install EPEL, you can build Cryptlib from source:
# Cryptlib
mkdir ~/libs
cd ~/libs
curl -OJ ftp://ftp.franken.de/pub/crypt/cryptlib/cl343.zip
mkdir cryptlib
cd cryptlib
unzip -a ../cl343.zip # -a enables text-mode
make shared # create libcl.so, not libcl.a
sudo install -o root -g root -m 755 libcl.so.3.4.2 /usr/local/lib
sudo ln -s libcl.so.3.4.2 /usr/local/lib/libcl.so
sudo install -o root -g root -m 644 cryptlib.h /usr/local/include
sudo bash -c 'echo "/usr/local/lib" > /etc/ld.so.conf.d/usr-local.conf'
sudo ldconfig
# Configure ODBC
odbcinst -j # check that the paths below are correct
# populate driver file
sudo emacs /etc/odbcinst.ini
# Example driver definitions
# Driver from the postgresql-odbc package
# Setup from the unixODBC package
[PostgreSQL]
Description = ODBC for PostgreSQL
Driver = /usr/lib/psqlodbcw.so
Setup = /usr/lib/libodbcpsqlS.so