forked from irrdnet/irrd-legacy
-
Notifications
You must be signed in to change notification settings - Fork 0
/
irrd-user.sgml
1684 lines (1670 loc) · 74.4 KB
/
irrd-user.sgml
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
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<book>
<title>IRRd - Internet Routing Registry Daemon
User/Configuration Guide</title>
<bookinfo>
<edition>IRRd User/Configuration Guide</edition>
<pubdate>February 2014</pubdate>
<corpauthor>Merit Network, Inc.</corpauthor>
<revhistory>
<revision>
<revnumber>2.1</revnumber>
<date>2001-09-17</date>
<authorinitials>ljb</authorinitials>
<revremark>
Initial release of SGML version of document.
</revremark>
</revision>
<revision>
<revnumber>2.1.2</revnumber>
<date>2001-09-24</date>
<authorinitials>ljb</authorinitials>
<revremark>
fixes/additions for documentation on irr_rpsl_submit.
</revremark>
</revision>
<revision>
<revnumber>2.1.3</revnumber>
<date>2001-10-18</date>
<authorinitials>ljb</authorinitials>
<revremark>
default location for binaries is now /usr/local/sbin
</revremark>
</revision>
<revision>
<revnumber>2.1.4</revnumber>
<date>2002-02-04</date>
<authorinitials>ljb</authorinitials>
<revremark>
document !u command. remove deprecated -m and -r options.
</revremark>
</revision>
<revision>
<revnumber>2.1.5</revnumber>
<date>2002-10-07</date>
<authorinitials>ljb</authorinitials>
<revremark>
new !o command. remove "redirect" command. RAToolSet now IRRToolSet.
</revremark>
</revision>
<revision>
<revnumber>2.2beta</revnumber>
<date>2003-08-08</date>
<authorinitials>ljb</authorinitials>
<revremark>
new cryptpw-access list. -N flag for irr_rpsl_submit.
</revremark>
</revision>
<revision>
<revnumber>2.2.1</revnumber>
<date>2004-11-18</date>
<authorinitials>ljb</authorinitials>
<revremark>
document irr_expansion_timeout command.
</revremark>
</revision>
<revision>
<revnumber>2.2.2</revnumber>
<date>2004-11-22</date>
<authorinitials>ljb</authorinitials>
<revremark>
note that IRRd now support RPSLng and that the
!i and !g commands are IPv4-only.
</revremark>
</revision>
<revision>
<revnumber>2.3.5</revnumber>
<date>2008-10-31</date>
<authorinitials>ljb</authorinitials>
<revremark>
Document the new !6 command
</revremark>
</revision>
<revision>
<revnumber>2.3.10</revnumber>
<date>2010-11-17</date>
<authorinitials>ljb</authorinitials>
<revremark>
Document the mirror_protocol config option
</revremark>
</revision>
<revision>
<revnumber>3.0.6</revnumber>
<date>2013-04-26</date>
<authorinitials>ljb</authorinitials>
<revremark>
Document new commands to support roa-status attribute.
</revremark>
</revision>
<revision>
<revnumber>3.0.7</revnumber>
<date>2014-02-18</date>
<authorinitials>ljb</authorinitials>
<revremark>
Add jwjs docs for import-via/export-via
</revremark>
</revision>
</revhistory>
<copyright>
<year>1999</year>
<year>2000</year>
<year>2001</year>
<year>2002</year>
<year>2003</year>
<year>2004</year>
<year>2008</year>
<year>2010</year>
<year>2013</year>
<holder>
The Regents of the University of Michigan ("The Regents") and
Merit Network, Inc. All rights reserved.</holder>
</copyright>
<legalnotice>
<para>
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
<orderedlist>
<listitem><para>
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
</para></listitem>
<listitem><para>
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
</para></listitem>
<listitem><para>
All advertising materials mentioning features or use of this software must display the following acknowledgement:
<blockquote><literallayout>
This product includes software developed by the University
of Michigan, Merit Network, Inc., and their contributors.
</literallayout></blockquote>
</para></listitem>
<listitem><para>
Neither the name of the University, Merit Network, nor the names of their contributors may be used to endorse or promote products derived from this software without specific prior written permission.
</para></listitem>
</orderedlist>
</para>
<para>THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. </para>
</legalnotice>
</bookinfo>
<chapter>
<title>Introduction</title>
<para>
IRRd is a stand-alone Internet Routing Registry database server. IRRd can store information and answer queries about local network, campus and ISP backbone topology, address allocation and routing policies. IRRd can be used as an independent local database server, or as part of the global Internet Routing Registry (IRR). The Internet Routing Registry is the union of a growing number of world-wide routing policy databases, including servers operated by Cable & Wireless, APNIC, Merit, RIPE, Verio, and many other organizations. See http://www.irr.net/docs/list.html for an up-to-date list of registries. </para>
<para>
IRRd supports the Routing Registry Specification Language (RPSL) routing registry syntax. As of version 2.2.0, IRRd also supports the RPSLng IPv6 and Multicast extensions to RPSL. The IRRd distribution includes all needed IRR support services, including: automated real-time mirroring of other IRR databases, update syntax checking, update security checking, and update notification. The current version of IRRd also supports several RIPEdb whois flags.</para>
<para>
When used in conjunction with policy tools such as RtConfig, Roe, and Aoe, the IRRd server allows:
</para>
<itemizedlist>
<listitem><para>
Automated generation of router configuration files and access-lists
</para></listitem>
<listitem><para>
Internet topology visualization
</para></listitem>
<listitem><para>
Network trouble-shooting and debugging
</para></listitem>
</itemizedlist>
<para>
In addition to user-oriented whois queries, the IRRd Server also provides several query commands for performing RPSL set expansions and AS number to route prefix mappings which are useful for automated tools (such as IRRToolSet). The IRRd distribution also includes the irr_rpsl_submit e-mail/TCP front-end update program which performs RPSL syntax and authentication checking.</para>
<section>
<title>Document Conventions</title>
<para>
The following document conventions are used in the IRRd User/Configuration Guide:</para>
<itemizedlist>
<listitem><para>
Commands and keywords are in <command>boldface</command>.
</para></listitem>
<listitem><para>
User-supplied variables are enclosed in <angle brackets>.
</para></listitem>
<listitem><para>
Optional elements are shown in [square brackets].
</para></listitem>
<listitem><para>
Alternative but required keywords are grouped in {braces} and separated by a vertical bar.
</para></listitem>
</itemizedlist>
</section>
<section>
<title>Getting Help</title>
<para>
The Merit IRRd development team accepts comments, requests, and bug reports at [email protected]. In addition, there is a public mailing list to share IRRd deployment and usage issues at [email protected]. List administravia requests should be directed to [email protected].</para>
</section>
<section>
<title>Credits</title>
<para>
Larry Blunk currently serves as the primary developer of IRRd at Merit. Project alumni include Dale Fay, Christerfer Frazier, Gerald Winters, Susan Harris, Craig Labovitz, Jon Poland and Matt Lewinsky.</para>
<para>
IRRd RPSL support was developed with funding from the National Science Foundation (NCR-9321060). Commercial funding from Merit Network, Inc. supported all other IRRd development.</para>
<para>
Portions of the IRRd code are based on software libraries from the MRT toolkit. MRT was originally developed by Merit Network, Inc., under National Science Foundation grant NCR-9318902, "Experimentation with Routing Technology to be Used for Inter-Domain Routing in the Internet." Additional MRT research was supported by the National Science Foundation (NCR-9710176) and gifts from Microsoft and the Intel Corporation. The design and ideas behind many of the MRT libraries draw heavily on the architecture pioneered in the GateD routing daemon.</para>
<para>
A large number of bug reports and fixes were provided by IRRd beta testers, including: Kevin Oberman (ESNet), Mark Prior (ConnectNet), John Heasly (Verio), and George Matey (Bay Networks).</para>
</section>
</chapter>
<chapter>
<title>Obtaining IRRd</title>
<para>
The IRRd source code may be freely modified and redistributed so long as the University of Michigan copyright notice is included with the redistribution. The latest IRRd source distribution can be found at the following website:</para>
<blockquote><literallayout>
http://www.irrd.net
</literallayout></blockquote>
<section>
<title>System Requirements</title>
<para>
IRRd should run on most Unix operating systems. Merit currently
targets Linux, Solaris, and FreeBSD for development and testing of IRRd.
IRRd maintains in-memory indexes of registry databases for
improved performance. Memory usage will depend on the number of objects
in each local or mirrored database.</para>
<para>
IRRd is generally I/O bound and does not require significant CPU cycles (with the exception of the period during infrequent database cleans to remove deleted objects).</para>
<para>
IRRd has been compiled and tested on a number of Unix platforms. The target platforms for development are Linux, Solaris, and FreeBSD.</para>
</section>
<section>
<title>Building and Installation Procedure</title>
<orderedlist>
<listitem><para>
Obtain the source archive and then unzip and untar it.
<blockquote><literallayout>
<prompt>% </prompt><userinput>cd /tmp</userinput>
<prompt>% </prompt><userinput>ftp ftp.merit.edu</userinput>
<prompt>ftp> </prompt><userinput>cd radb/irrd/source</userinput>
<prompt>ftp> </prompt><userinput>get irrd.tar.gz</userinput>
<prompt>ftp> </prompt><userinput>quit</userinput>
<prompt>% </prompt><userinput>cd /usr/local/src</userinput>
<prompt>% </prompt><userinput>gzip -cd < /tmp/irrd.tar.gz | tar xvf -</userinput>
</literallayout></blockquote>
</para></listitem>
<listitem><para>
Change into the irrd directory and run <command>./configure</command>.
<blockquote><literallayout>
<prompt>% </prompt><userinput>cd /tmp/irrd-<version>/src</userinput>
<prompt>% </prompt><userinput>./configure</userinput>
Several options can be specified as parameters to the configure command:
<prompt>% </prompt><userinput>./configure --disable-threads</userinput> Disable thread support
<prompt>% </prompt><userinput>./configure --disable-wall</userinput> Disable -Wall gcc option
<prompt>% </prompt><userinput>./configure --with-gdbm</userinput> Support GNU DBM database files
<prompt>% </prompt><userinput>./configure --with-pgpv5</userinput> Prefer PGP V5 over default of GnuPG.
</literallayout></blockquote>
</para></listitem>
<listitem><para>
Now run make. After successful compilation, you will have binaries in each of the program directories..
<blockquote><literallayout>
<prompt>% </prompt><userinput>make</userinput>
</literallayout></blockquote>
</para></listitem>
<listitem><para>
Run make install. By default, binaries will be installed in /usr/local/sbin. Use
the --prefix option with configure to change the default install directory.
<blockquote><literallayout>
<prompt>% </prompt><userinput>su</userinput>
<prompt># </prompt><userinput>make install</userinput>
</literallayout></blockquote>
</para></listitem>
<listitem><para>
See Section 5 for information on configuring email and TCP object submission.
</para></listitem>
</orderedlist>
</section>
</chapter>
<chapter>
<title>Using IRRd</title>
<section>
<title>Getting Started</title>
<para>
Before using IRRd, you will need to obtain an initial copy of the IRR databases. The IRRd distribution includes a tool, IRRdCacher, which can be used to fetch and maintain copies of the IRRd databases. The tool and instructions are available as part of the IRRd distribution.</para>
<para>
See Appendix A for more information about IRRdCacher.</para>
<para>
By default, IRRd expects to find copies of the databases (cw.db, radb.db, etc.) in /var/spool/databases. This default IRR directory may be overridden with the -d command line flag, or the irr_directory config file entry.</para>
<para>
For real-time mirroring, you will need to contact the database administrators to obtain the appropriate IP address and port number used for mirroring service.</para>
<para>
By default, IRRd listens for queries on the standard whois TCP port 43. Alternatively, the whois port number may be specified by the irr_port configuration command.</para>
<para>
In addition, IRRd listens for user configuration/management telnet connections by default on TCP port 5673. You can optionally specify the port on which the server listens for telnet connections by adding the following line to /etc/services. Feel free to choose your own port numbers.</para>
<blockquote><literallayout>
irrd 5674/tcp # IRRd routing registry server
</literallayout></blockquote>
<para>
The daemon may be configured by editing a configuration file, or by invoking the configuration utility from the interactive user telnet interface. The interactive interface features a Cisco System. Below is an example of telneting to the user interactive interface (UII) port on a machine running IRRd.</para>
<blockquote><literallayout>
>telnet 127.0.0.1 irrd
IRRd version 2.1.3 [10/18/2001]
User Access Verification
foo password: *****
foo IRRd#
</literallayout></blockquote>
<para>
If a password is specified in the configuration file, it must be supplied at the password prompt. Initially, IRRd defaults to no password access control and restricts user interactive telnet to the loopback address or the interface address of the local machine.</para>
</section>
<section>
<title>IRRd Synopsis</title>
<cmdsynopsis>
<command>irrd</command>
<arg>-a</arg>
<arg>-d <replaceable>database_dir</replaceable></arg>
<arg>-f <replaceable>conf_file</replaceable></arg>
<arg>-g <replaceable>group_name</replaceable></arg><sbr>
<arg>-l <replaceable>user_name</replaceable></arg>
<arg>-n</arg>
<arg>-s <replaceable>password</replaceable></arg>
<arg>-u</arg>
<arg>-v</arg>
<arg>-w <replaceable>irr_port</replaceable></arg>
<arg>-x</arg>
</cmdsynopsis>
</section>
<section>
<title>Options</title>
<informaltable frame='none'>
<tgroup cols='2'>
<colspec colwidth='1.5in'>
<colspec colwidth='4.5in'>
<tbody>
<row>
<entry><option>-a</option></entry>
<entry>Enable atomic transactions for database updates</entry>
</row>
<row>
<entry><option>-d <path></option></entry>
<entry>Set database directory</entry>
</row>
<row>
<entry><option>-f <conf file></option></entry>
<entry>Specify the configuration file to use (default: /etc/irrd.conf)</entry>
</row>
<row>
<entry><option>-g <group name></option></entry>
<entry>Drop priveleges to given group name</entry>
</row>
<row>
<entry><option>-l <user name></option></entry>
<entry>Drop priveleges to given user name</entry>
</row>
<row>
<entry><option>-n</option></entry>
<entry>Do not daemonize</entry>
</row>
<row>
<entry><option>-s <password></option></entry>
<entry>Set the UII password</entry>
</row>
<row>
<entry><option>-u</option></entry>
<entry>Don't allow privileged commands</entry>
</row>
<row>
<entry><option>-v</option></entry>
<entry>Verbose logging, debug mode</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section>
<title>Description</title>
<para>
IRRd is a complete Internet Routing Registry Server supporting indexing, mirroring, whois queries, and email/TCP updates. Interactive telnet connections are on port "irrd" in /etc/services.</para>
</section>
<section>
<title>Interactive Interface</title>
<para>
IRRd provides an interactive user interface that can be used to control various and operational aspects of IRRd and show the current status of the daemon.</para>
<para>
The port number can be specified in the configuration file. The default is TCP port 5673, or the number associated with "irrd" in /etc/services. If a password is specified in the configuration file, it must be supplied on login.</para>
<para>
Unix shell-like redirection (or filename) is available for output. To edit a line, emacs-like line editing including ^a, ^b, ^e, ^f, ^d, ^k, ^u and ^c is available. To reuse a previous line, tcsh-line history function is available by typing ^p and ^n.</para>
<para>
The IRRd command language shares many similarities with the language used on Cisco Systems routers. Commands include:</para>
<itemizedlist>
<listitem><para>
<command>show config</command> -- view the configuration file
</para></listitem>
<listitem><para>
<command>show version</command> -- show the current version
</para></listitem>
<listitem><para>
<command>show threads</command> -- show the status of application threads
</para></listitem>
<listitem><para>
<command>show connections</command> -- show current TCP tool queries
</para></listitem>
<listitem><para>
<command>reboot</command> -- restart the daemon
</para></listitem>
<listitem><para>
<command>help</command> -- shows all commands available
</para></listitem>
<listitem><para>
<command>exit</command> -- leave the UII interface
</para></listitem>
<listitem><para>
<command>mirror</command> -- synchronize database with remote server
</para></listitem>
<listitem><para>
<command>reload</command> -- reload an IRR database file
</para></listitem>
<listitem><para>
<command>show database</command> -- show database status
</para></listitem>
<listitem><para>
<command>dbclean</command> -- synchronize IRR diskfiles with memory
</para></listitem>
</itemizedlist>
<para>
Below is an example of a user interactive telnet command to the IRRd daemon:</para>
<literallayout><computeroutput>
[47] IRRd> show databases
Database Size (kb) Rt Obj AutNum Obj Serial #
-------- --------- ------ ---------- --------
cw 6722.3 40076 435 0
radb 10257.5 42913 1083 19889
ripe 3823.7 16854 1461 1312991
cw mirroring whois.radb.net
radb mirroring whois.radb.net
ripe mirroring whois.radb.net
</computeroutput></literallayout>
</section>
<section>
<title>Getting Status Information from IRRd</title>
<para>
<command>show mirror-status</command> -- shows the status of mirroring a remote repository.</para>
<para>
This command makes it possible to determine whether your repository and the remote repository are synchronized. Use of the show mirror-status command requires that both repositories support the "!j" functionality."</para>
<screen>
For example:
show mirror-status telstra
telstra (Mirror)
Local Information:
Oldest journal serial number: 31
Current serial number: 1810
Remote Information:
Mirror host: 203.50.0.201:43
Mirrorable.
Oldest journal serial number: 1.
Current serial number: 1810.
Last exported at serial number: 1810.
</screen>
<para>
The local information shows the oldest serial number in your local journal (for providing third-party mirroring of the remote repository) and the current serial number in your local repository. The remote information shows the status of the repository, where it is mirrored, its oldest journal number for mirroring, and the database's current serial number. In the above example, the local current serial number and the remote current serial number are the same, and thus the databases are in sync.</para>
<para>
When a repository that doesn't support !j functionality, such as the RIPE server, is queried, output such as the following is returned:</para>
<screen>
ripe (Mirror)
Local Information:
Oldest journal serial number: 13037243
Current serial number: 13051817
Remote Information:
Mirror host: 193.0.0.200:43
Remote status query unsupported.
</screen>
<para>
<command>show statusfile</command> -- shows location of the IRRD_STATUS file.</para>
<para>
IRRd version 2.0 makes it possible to store additional state information for remote repositories. This data is used for responses to the show mirror-status command and other queries. By default, the <filename>IRRD_STATUS</filename> file is stored in your IRRd configuration directory and is called <filename>IRRD_STATUS</filename>. You can use the set statusfile command to set a different location. </para>
<para><command>set statusfile</command> -- sets location of the <filename>IRRD_STATUS</filename> file.</para>
</section>
<section>
<title>Configuration Commands</title>
<para>
When IRRd is started for the first time and no configuration file exists on disk, the programs will create a default configuration in volatile memory. This configuration may be modified in memory by issuing the "config" command from the UII telnet interface prompt. Modifications to volatile memory may be saved to disk using the "write" command. Modifications not saved to disk will be lost if the daemon terminates or is rebooted.</para>
<para>
Upon startup, IRRd will search for the default configuration file for the daemon (usually /etc/irrd.conf). The user may also override the default configuration file by providing a "-f <filename>" flag on the command line of the daemon.</para>
<para>
IRRd supports the following configuration commands:</para>
<para><command>
password <string> [<access-list-num>]</command></para>
<para>
Sets a password <string> for the telnet interface. Note that if a password is not set, access verification will not be performed and interactive user telnet connections will only be allowed from the localhost. If <access-list-num> is specified, telnet connections will be restricted to IP addresses allowed by the access list. See the access-list description below for more information.</para>
<para><command>
uii port <number></command></para>
<para>
Changes the port number with <number> for the telnet interface. The default is the value specified in /etc/services for the daemon name "irrd". If an /etc/services entry does not exist, the port number defaults to 5673.</para>
<para><command>
debug <server|submission> file-name <filename></command></para>
<para>
<command>
debug <server|submission> file-max-size <bytes></command> </para>
<para>
<command>
debug <server|submission> syslog</command></para>
<para>
<command>
debug <server|submission> verbose</command></para>
<para>
Turns on logging for the IRRd server or object submission by the email/tcp irr_rpsl_submit process. file-name specifies the disk file, or "stdout." file-max-size bytes automatically truncates the log file at <size> byes. Configuring syslog sends logging information to syslog on the local machine. Verbose enables verbose logging.</para>
<para><command>
access-list <number> {permit|deny} <prefix> [refine|exact]</command>
</para>
<para>
Defines an access list <number>, which permits or denies access if the condition is matched. all can be specified as <prefix>. exact will be assumed if neither refine or exact is specified. exact matches only the prefix, while refine matches more specific prefixes, excluding the prefix itself.</para>
<para>
Matches are performed in the order in which they appear. At the end of a list with the same number, permit all is assumed.</para>
<para>
<number> must be an integer between 1 and 1000.</para>
<para>For example:</para>
<screen>
! Access only from Merit Nets
access-list 1 permit 198.108.60.0/24 refine
access-list 1 permit 198.108.0.0/24 refine
access-list 99 deny all
</screen>
<para>
<command>!</command> -- comment and separator</para>
<para>Comments can appear at the beginning of a line, or any other place in the line. A comment at the beginning of a line is treated as a separator, which ends a command clause followed by its sub-commands.</para>
<para>
<command>irr_directory <path></command></para>
<para>
Specify the path for the cache directory and database files.</para>
<para>
<command>ftp directory <path></command></para>
<para>Specify the directory in which to copy files for ftp access. Also see the irr_database export command below.</para>
<para>
<literallayout>
<command>irr_database <name> [mirror_host <hostname> [port <port number>] ]</command>
<command>irr_database <name> [mirror_protocol <num>]</command>
<command>irr_database <name> [authoritative]</command>
<command>irr_database <name> [access <num>]</command>
<command>irr_database <name> [write-access <num>]</command>
<command>irr_database <name> [mirror-access <num>]</command>
<command>irr_database <name> [cryptpw-access <num>]</command>
<command>irr_database <name> [filter
[non-critical|routing-registry-objects|<object name>]
| [~(non-critical|routing-registry-objects|<object name>)]</command>
<command>irr_database <name> [export <export interval>]</command>
<command>irr_database <name> [roa-data]</command>
</literallayout>
</para>
<para>
Include a database named <name>.db in the IRR directory in the list of databases provided by the server. If available, enable automatic mirroring to hostname on the selected port (default is 43).</para>
<para>
If the authoritative keyword is used, updates will be allowed for this database.
</para>
<para>
Access restricts read, write and mirror access to IP addresses permitted by access-list <num>.</para>
<para>
Write access refines access and limits updates to IP addresses permitted by access-list <num>. By default, write access is restricted to the loopback address of the local machine. Mirror-access refines access and limits database mirroring to IP addresses permitted by access-list <num>.
cryptpw-access limits access to hashed passwords in mntner auth: attributes. If this access list is set, only allowed hosts will be shown CRYPT-PW hash strings in queries and mirror requests. Denied hosts will instead see the string "HIDDENCRYPTPW" in place of the actual hash.</para>
<para>
mirror_host and mirror_protocol defines the mirrored host and protocol used for mirrored databases. The default mirroring protocol is 1 if the mirror_protocol is not specified. Optionally, mirror protocol 3 is also supported for the RIPE registry. Mirror protocol 2 is not currently supported.</para>
<para>
Some databases (like RIPE) contain a significant volume of non-routing related information like person objects and role objects. To reduce the size of the database, you can use the filter command to specify the objects you want to include (or not include) in your database.</para>
<para>
The export option will atomically copy the database into the ftp_dir directory for exporting.</para>
<para>
If the roa-data keyword is used, this database contains RPKI based
roa-status attributes. This database is used to generate the roa-status
attribute for route and route6 objects when the -R query flag is specified.
This database is not otherwise queried or referenced.
</para>
<para>
<command>roa-disclaimer <string></command></para>
<para>Add a disclaimer message to responses which contain a roa-status
attribute. This may be required due to RIR Relying Party Agreements.
Longer messages may be broken into
multiple lines by specifying multiple roa-disclaimer commands.</para>
<para>
<command>irr_mirror_interval <seconds></command></para>
<para>The interval for obtaining mirror updates. The default is 10 minutes.</para>
<para><command>irr_port <port> [access <num>]</command></para>
<para>The port to listen on for "RAWhoisd" style machine TCP connections. The optional access num specifies an access list to globally restrict incoming connections.</para>
<para><command>irr_max_connections <number></command></para>
<para>Limit the number of simultaneous queries. The default is 25 connections.</para>
<para><command>irr_expansion_timeout <number></command></para>
<para>Limit the amount of time (in seconds) that set expansion queries are allowed to consume. Expansion queries which exceed this value will be aborted and an error returned. A value of zero indicates no timeout on expansions. The default value is zero (no timeouts).</para>
<para><command>dbclean [interval <number of seconds>]</command></para>
<para>Sychronize the disk database files with IRRd memory. During normal operation, IRRd marks updated or deleted objects with a special flag. By default, IRRD rebuilds the database.db (without these deleted objects) once every 24 hours.</para>
<para>
<command>no dbclean</command></para>
<para>Disable database cleaning.</para>
</section>
<section><title>
Configuration Commands for irr_rpsl_submit</title>
<para>
The following configuration commands control the behavior of the IRRd submission module:</para>
<para>
<command>irr_server <host></command></para>
<para>
The IRRd IP network address of the remote IRR server. Defaults to "localhost".</para>
<para>
<command>irr_port <port> [access <num>]</command></para>
<para>
The IRRd command/query port and optional access list. The default is 43.</para>
<para>
<command>override_cryptpw <password></command></para>
<para>The encrypted password used for overriding normal authentication checks.
The default is "piSFDzJu5e1wY" (i.e., foo).</para>
<para>
<command>pgp_dir <path></command></para>
<para>
The directory path of the PGP ring files. The default is ~/.pgp</para>
<para>
<command>db_admin <email address></command></para>
<para>
The email address of the DB administrators. The default is db-admin@localhost.</para>
<para>
<command>reply_from <email address></command></para>
<para>
The email address to be used in the From: and Reply-to: fields in responses.</para>
<para>
Database submissions will be sent to 'irr_port' and 'irr_server'. The defaults are host 'localhost' and port 43. The 'override_cryptpw' command sets the system password and is typically used by an administrator to enter new maintainer objects into the system. Two log files are created: a submission log 'trans.log' and an acknowledgement log 'ack.log'. The log files will be created by default in the directory specified by 'irr_directory' (i.e., the IRRd cache directory). The default can be overridden with the 'submission_log_dir' configuration command.</para>
<para>
The 'pgp_dir' configuration command specifies the directory location of the public and secret PGP ring files. The default is the normal PGP default, ~/.pgp from the UID of the invoking process. The 'pgp_dir' command is useful, for example, when sendmail invokes the DB submission process from /etc/aliases running under user 'daemon'. Note that the PGP directory will need to be permitted properly to allow access from the irr_rpsl_submit process. Alternatively, one may want to install the irr_rpsl_submit binary as set-uid to a particular ID which has access to the PGP directory.</para>
<example>
<title>Sample Configuration File</title>
<para>
After editing the configuration file, the user may return to the top-level of the interactive telnet interface by typing a ^Z or entering exit. Here is an example of an IRRd confguration file:</para>
<programlisting>
!
! Test config file
!
password xxxxxx
uii_port 5673
!
! The cache directory
irr_directory /var/irr/databases/
debug server file-name /var/spool/log/irrd.log
debug submission file-name /var/spool/log/irr-email.log
!
! The port of whois and IRRToolset connections
irr_port 43
!
! Make sure we don't get overwhelmed
irr_max_connections 64
!
irr_mirror_interval 1800
irr_database radb mirror_host whois.radb.net
irr_database localdb authoritative
irr_database localdb access 1
!
db_admin [email protected]
override_cryptpw EhjhsdhEhjhsd
pgp_dir /irr/etc/.pgp
irr_server whois.radb.net
!
! Access only from Merit Nets
access-list 1 permit 198.108.60.0/24 refine
access-list 1 permit 198.108.0.0/24 refine
access-list 99 deny all
</programlisting>
</example>
</section>
</chapter>
<chapter>
<title>Querying IRRd</title>
<para>
RADB-style machine telnet queries are available on the port specified in the configuration file. Although IRRd was designed for use by tools such as RtConfig, peval, and PRtraceroute, it is also useful for compute-intensive queries generated by individuals.</para>
<para>
IRRd supports two modes: single command mode and multiple command mode.</para>
<para>
<command>Single command mode</command> -- the query server processes one command, returns the results to the server, and closes the connection. This is the default mode for IRRd, and the normal operation of a whois server.</para>
<para>
<command>Multiple command mode</command> -- the query server continues to accept and service query requests on the connection until the remote user issues a quit command. See Appendix B for more information about IRRd's multiple-command mode.</para>
<example>
<title>Whois Queries</title>
<para>
IRRd also supports standard RPSL whois queries. For example:</para>
<literallayout>
whois -h whois.radb.net 128.223.0.0/16
</literallayout>
<para>
The output is an IRR route object:</para>
<literallayout><computeroutput>
route: 128.223.0.0/16
descr: UONet
University of Oregon
Computing Center
Eugene, OR 97403-1212
USA
origin: AS3582
mnt-by: MAINT-AS3582
changed: [email protected] 19960222
source: RADB
</computeroutput></literallayout>
</example>
</chapter>
<chapter>
<title>Updating IRRd with irr_rpsl_submit</title>
<para>
When using IRRd to run an authoritative database registry (as opposed to simply mirroring other registries), it will be necessary to configure the irr_rpsl_submit program to accept e-mail and/or TCP based object submisssions. This program performs RPSL syntax checking and maintainer authorization verification and acts as a front-end for IRRd.</para>
<para>
The irr_rpsl_submit command is configured by command line flag values, by setting configuration commands in the IRRd configuration file, or by a combination of both. Command line options override options set in the IRRd configuration file.</para>
<section>
<title>irr_rpsl_submit Synopsis</title>
<cmdsynopsis>
<command>irr_rpsl_submit</command>
<arg>-c <replaceable>encrypted system password</replaceable></arg>
<arg>-D</arg><sbr>
<arg>-E <replaceable>DB admin address</replaceable></arg>
<arg>-f <replaceable>IRRd conf file</replaceable></arg><sbr>
<arg>-F <replaceable>response footer string</replaceable></arg>
<arg>-h <replaceable>irrd host</replaceable></arg><sbr>
<arg>-l <replaceable>log directory</replaceable></arg>
<arg>-N</arg><sbr>
<arg>-p <replaceable>irrd port</replaceable></arg>
<arg>-r <replaceable>pgp directory</replaceable></arg>
<arg>-R</arg><sbr>
<arg>-s <replaceable>authoritative DB source</replaceable></arg>
<arg>-v</arg>
<arg>-x</arg>
<arg>filename</arg>
</cmdsynopsis>
</section>
<section>
<title>Options</title>
<informaltable frame='none'>
<tgroup cols='2'>
<colspec colwidth='1.5in'>
<colspec colwidth='4.5in'>
<tbody>
<row>
<entry><option>-c <password></option></entry>
<entry>Encrypted password that overrides normal authentication checks. The encrypted password is ciphertext generated using the crypt(3) utility. We also helpfully provide the crypt_gen.c file in the programs/irr_util directory.</entry>
</row>
<row>
<entry><option>-D</option></entry>
<entry>Read input from STDIN for direct/TCP (non-email) submissions</entry>
</row>
<row>
<entry><option>-E <DB email></option></entry>
<entry>Email address for DB admin mail</entry>
</row>
<row>
<entry><option>-f <config file></option></entry>
<entry>IRRd configuration file location</entry>
</row>
<row>
<entry><option>-F <footer string></option></entry>
<entry>enclosed response footer string to add to messages</entry>
</row>
<row>
<entry><option>-h <server></option></entry>
<entry>IRRd host/server</entry>
</row>
<row>
<entry><option>-l <log dir></option></entry>
<entry>Log directory location</entry>
</row>
<row>
<entry><option>-N</option></entry>
<entry>permit inetnum/inet6num/as-block/domain objects</entry>
</row>
<row>
<entry><option>-p <port></option></entry>
<entry>IRRd port number</entry>
</row>
<row>
<entry><option>-r <pgp dir></option></entry>
<entry>PGP ring files location</entry>
</row>
<row>
<entry><option>-R</option></entry>
<entry>RPS Dist mode</entry>
</row>
<row>
<entry><option>-s <db name></option></entry>
<entry>Specify authoritative database source</entry>
</row>
<row>
<entry><option>-v</option></entry>
<entry>Turn on verbose debugging/logging</entry>
</row>
<row>
<entry><option>-x</option></entry>
<entry>Suppress notifications. The database will be updated but notifications will not be sent</entry>
</row>
<row>
<entry><option>filename</option></entry>
<entry>Input filename</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section>
<title>Description</title>
<para>
irr_rpsl_submit accepts e-mail updates and controls the process of entering and modifying database data. irr_rpsl_submit can perform PGP authentication, the standard authentication mechanisms of encrypted password and mail-from, syntax checking, and standard RIPE/RPSL notifications.</para>
<para>The '-f' and '-p' options specify the IRRd daemon location. The defaults are localhost and port 43. The '-c' option specifies the system encrypted password used to override normal authentication checking. The default is "piSFDzJu5e1wY" (i.e., foo). '-D' causes irr_rpsl_submit to read from STDIN and disables mail feedback (for use in direct/TCP-based submissions). '-f' specifies the IRRd configuration file location. /etc/irrd.conf is the default. '-l' specifies the location for the acknowledgement and transaction logs. The default is the 'irr_directory' value from /etc/irrd.conf.
'-r' gives the PGP ring files location. The default is ~/.pgp in the user's home directory. '-s' specifies authoritative databases. irr_rpsl_submit will only allow updates to authoritative databases and will signal an error for all others. The '-s' option may appear multiple times as necessary. '-x' stops notifications from being sent. 'filename' is the name of the input file.</para>
<para>
The irr_rpsl_submit flag options override options in the IRRd configuration file. These options enable irr_rpsl_submit to reside on a remote machine from IRRd and to operate without an IRRd configuration file.</para>
</section>
<section>
<title>Configuration Commands</title>
<para>
When an IRRd submission instance is invoked, the default IRRd configuration file is scanned for configuration information (/etc/irrd.conf). The default configuration path can be overridden with the "-f <filename>" command line option.</para>
<para>
For a listing of configuration commands that control the behavior of the IRRd submission module, see Section 3.</para>
</section>
<section>
<title>Invoking irr_rpsl_submit</title>
<para>
Many users will find it convenient to register irr_rpsl_submit in their Unix /etc/aliases file to allow convenient remote mail access. Note that a link to irr_rpsl_submit in /etc/smrsh will be needed for those systems which employ the Sendmail restricted shell (i.e. RedHat Linux). Also note that if PGP support is enabled, the irr_rpsl_submit process will need to be able to read/write the PGP directory configured by pgp_dir. This can be achieved by installing the irr_rpsl_submit process as set-uid to a particular ID and permit read/write access to the PGP directory from that ID. Below is an example /etc/aliases entry for use with sendmail:</para>
<para>
<command>auto-dbm: "|/usr/local/sbin/irr_rpsl_submit -f /etc/conf/irrd.conf"</command></para>
<para>
The '-f' option gives the location of the IRRd configuration file. Any of the other flag options listed above can also be used.</para>
<para>
Some additional utilities are bundled with the IRRd distribution, including mailloopbreak.pl which can be used in from of irr_rpsl_submit in the /etc/alias file to detect, and prevent mail loops from the irr-submit auto-generated email messages.</para>
</section>
<section>
<title>System Requirements</title>
<para>
The irr_rpsl_submit module is a non-threaded application and is part of the IRRd software distribution. GunPG or PGP 5.0 (or higher) must be installed if you want irr_rpsl_submit to support PGP authentication.</para>
</section>
<section>
<title>irr_rpsl_submit Quick Start</title>
<para>
Here are step-by-step instructions for obtaining and installing irr_rpsl_submit to handle submissions:</para>
<orderedlist>
<listitem>
<para>
Grab and build an IRRd source code distribution: See Section 2 for these steps.</para></listitem>
<listitem><para>
Initialize the /etc/irrd.conf file by adding the following entries:
<blockquote><literallayout>
override_cryptpw EWUZmlvOSvHmk ! sets system password to "foo"
pgp_dir <your ~/.pgp path> ! example: /usr/users/joe/.pgp
</literallayout></blockquote>
</para></listitem>
<listitem><para>
Execute IRRd.
<blockquote><literallayout>
(See Section 2 for instructions on building IRRd)
% /usr/local/sbin/irrd
</literallayout></blockquote>
</para></listitem>
<listitem><para>
To allow email submissions, add the following to /etc/aliases (also add a link to irr_rpsl_submit in /etc/smrsh if using the Sendmail restricted shell and verify that the pgp_dir is permitted to allow read/write access to the process):
<blockquote><literallayout>
auto-dbm: "|/usr/local/sbin/irr_rpsl_submit"
</literallayout></blockquote>
</para></listitem>
<listitem><para>
To allow TCP submissions, add the following to /etc/services:
<blockquote><literallayout>
irr_rpsl_submit 8888/tcp
</literallayout></blockquote>
</para></listitem>
<listitem><para>
Add the following to your /etc/inetd.conf (note the following should be on one continuous line) and restart inetd:
<blockquote><literallayout>
irr_rpsl_submit stream tcp nowait daemon
/usr/local/sbin/irr_rpsl_submit irr_rpsl_submit -D
</literallayout></blockquote>
</para></listitem>
</orderedlist>
</section>
</chapter>
<chapter>
<title>Submitting Email Updates</title>
<para>
This is a brief explanation of how to send email updates to an IRRd server (via irr_rpsl_submit). It is intended as a sort of 'quick start' document, detailing only the minimum steps necessary to register. It is assumed that you are somewhat familiar with RPSL-style routing registries and RPSL routing policy syntax.</para>
<section>
<title>Updates and Changes</title>
<para>
This document provides templates for registering three types of objects in the RADB:</para>
<para><literallayout><computeroutput>
Object Contents
Maintainer object Specifies authorization for objects
AS object Administration and routing policy of an AS
Route object A single route to be added to the registry
</computeroutput></literallayout>
</para>
<section>
<title>Step One - Register One or More Maintainers</title>
<para>
Maintainer objects specify which parties are allowed to perform updates to the RADB, and how these parties are authenticated. When a route or AS object is submitted for registration, a Maintainer object must be referenced; otherwise the submission will be rejected. Thus, the first step to registering information in the IRR is to register one or more Maintainer objects. To do this, first determine the names and email addresses of those who will be allowed to update AS and Route objects. Then copy the maintainer object template below into an email message, filling in the fields with the appropriate information, and send it to database administrators (usually db-admin@<domain>). A human will read this message and add the information to the registry.</para>
<para>
Maintainer objects need mnt-by attributes just like any other object. You should make sure that the maintainer objects you register contain a mnt-by attribute and its value should be the value of the mntner attribute. This self-reference specifies that updates to this maintainer object are allowed only from those authorization mechanisms specified in the maintainer object. Failure to register a maintainer object in this way means that anyone could modify that maintainer and subsequently modify the objects it references.</para>
<example>
<title>Maintainer Template</title>
<literallayout>
---------------------- CUT HERE -------------------
mntner:
descr:
admin-c:
tech-c:
upd-to:
mnt-nfy:
mnt-by:
auth:
changed:
source:
---------------------- CUT HERE -------------------
</literallayout>
</example>
<example>
<title>Maintainer Example</title>
<literallayout><computeroutput>
mntner: MAINT-AS237
descr: Maintainer for AS 237
admin-c: Andrew L. Adams
tech-c: Andrew L. Adams
upd-to: [email protected]
mnt-nfy: [email protected]
mnt-by: MAINT-AS237
auth: MAIL-FROM [email protected]
auth: MAIL-FROM [email protected]
changed: [email protected] 941219
source: RADB
</computeroutput></literallayout>
</example>
<para>
NOTE: Send only Maintainer objects to db-admin@<domain>. AS, Route and other objects must be sent to auto-dbm@<domain>. Of all the objects, only Maintainer objects undergo a human check before being committed to the registry and therefore, as might be expected, registration of Maintainer objects takes longer than registration of AS and Route objects. Turnaround time on Maintainer objects is on the order of hours rather than seconds, as in the case of other objects.</para>
<para>
Once the Maintainer object is created, modifications can be sent to [email protected]. The new object will automatically replace the old one.</para>
</section>
<section>
<title>Step Two - Register AS and Policy Information</title>
<para>
After registering a Maintainer object, the next step is to register an AS object, thereby specifying an AS's routing policy. Because AS objects are referenced by Route objects, they must be registered before Route objects. To do this, first determine how to express the AS policy in RPSL syntax. Then copy the AS object template below into an email message, filling in the fields with the appropriate information, and send it to auto-dbm@<database>. This message will immediately be checked for proper syntax and some semantic checks will be performed. If errors are detected, it will be returned to you with annotations describing the errors. Otherwise, the AS object will be added to the registry.</para>
<para>
Note that the mnt-by field should contain the string you submitted in the mntnr field of the Maintainer object.</para>
<example>
<title>AS Template</title>
<literallayout><computeroutput>
---------------------- CUT HERE -------------------
aut-num:
descr:
import:
export:
default:
admin-c:
tech-c:
remarks:
remarks:
mnt-by:
changed:
source: RADB
---------------------- CUT HERE -------------------
</computeroutput></literallayout>
</example>
<example>
<title>AS Example</title>
<literallayout><computeroutput>
aut-num: AS3582
as-name: UONET
descr: University of Oregon
import: from AS689
action pref=10;
accept NOT ANY
import: from AS1798
action pref=10;
accept AS1798 AND NOT {0.0.0.0/0}
import: from AS2914
action pref=10;
accept <^AS-WNA*$> AND NOT {0.0.0.0/0}
import: from AS3701
action pref=10;
accept ANY AND NOT {0.0.0.0/0}
import: from AS3838
action pref=10;
accept AS-SNS AND NOT {0.0.0.0/0}
import: from AS4222
action pref=10;
accept <^AS-LEN*$> AND NOT {0.0.0.0/0}
import: from AS5650
action pref=10;
accept AS-ELICUST AND NOT {0.0.0.0/0}
import: from AS6447
action pref=10;
accept <^AS-OREGON-IX*$> AND NOT {0.0.0.0/0}
import: from AS10876
action pref=10;
accept <^AS-MAOZ*$> AND NOT {0.0.0.0/0}
export: to AS689
announce AS3582
export: to AS1798
announce AS3582
export: to AS2914
announce AS3582
export: to AS3701
announce AS3582
export: to AS3838
announce AS3582
export: to AS4222
announce AS3582
export: to AS6447
announce AS3582