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
|
<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<guide link="/proj/en/base/embedded/gnap-userguide.xml">
<title>Gentoo Network Appliance (GNAP) User Guide</title>
<author title="Author">
<mail link="koon@gentoo.org">Thierry Carrez</mail>
</author>
<abstract>
This document describes how to use GNAP, a tool to produce Network
Appliance systems based on Gentoo.
</abstract>
<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
<license/>
<version>2.0</version>
<date>April 20, 2006</date>
<chapter>
<title>GNAP basics</title>
<section>
<title>Goal</title>
<body>
<p>
The goal is to use your current Gentoo system (called the <e>host</e>)
to build a LiveCD or a disk with a bootable Network Appliance system, complete
with customized configuration files, that you can use to boot another system
(called the <e>target</e>).
</p>
<p>
GNAP provides a prebuilt system image, called the <e>GNAP core</e>. You can
modify the default configuration of this image by providing new configuration
files that will be overlaid over the system image during the target boot.
</p>
<p>
The <c>gnap_overlay</c> script takes a GNAP core tarball and one or more
<e>overlay sources</e> and either produces a bootable LiveCD .iso file, or
writes a bootable filesystem to a disk device (typically a CompactFlash card
or DOM):
</p>
<figure link="gnap_overlay.png" short="gnap_overlay principle"
caption="How gnap_overlay works"/>
</body>
</section>
<section>
<title>The overlay sources</title>
<body>
<p>
There are two types of overlay sources you can use with
<c>gnap_overlay</c>: directories and <e>conflet</e> files.
</p>
<p>
Overlay directories are just directories containing files that will be copied
over the root filesystem during the target boot. The root of the directory
corresponds to the root of the target filesystem, so it typically contains
an <path>etc/</path> subdirectory containing files that will be copied over
the <path>/etc</path> target directory.
</p>
<p>
<e>Conflet</e> files are just .tar.bz2 compressed tarballs containing an
overlay directory. They usually contain typical reusable configuration changes,
making it easier to maintain several configurations.
</p>
<impo>
At the moment only the <path>/etc</path>, <path>/var</path>, <path>/tmp</path>,
<path>/home</path>, <path>/root</path> and <path>/mnt</path> target directories
are writable on the target at boot time, meaning your overlay sources cannot
specify files outside these directories.
</impo>
</body>
</section>
<section>
<title>The overlay.conf file</title>
<body>
<p>
The <e>overlay.conf</e> file controls general target customization options,
like localization options and which features should be enabled on your GNAP
target. It must be present either in an overlay source (as
<path>etc/overlay.conf</path>) or directly specified as a <c>-c</c> parameter
to <c>gnap_overlay</c>.
</p>
</body>
</section>
</chapter>
<chapter>
<title>Your first GNAP LiveCD</title>
<section>
<title>Installing GNAP</title>
<body>
<p>
GNAP is available through Gentoo Portage. Simply emerge it using (as root):
</p>
<pre caption="GNAP installation">
# emerge gnap
</pre>
<warn>
GNAP might only be available in "~x86". Adjust your
<path>/etc/portage/package.keywords</path> file if needed.
</warn>
<note>
This will fetch the GNAP core file, which is usually quite large (~14Mb). You
can set the "minimal" USE flag if you don't want to download the GNAP core,
but only install the GNAP tools.
</note>
<note>
Users of other flavors of Linux should refer to the
<uri link="">Using GNAP on non-Gentoo hosts</uri> guide.
</note>
</body>
</section>
<section>
<title>Preparing your overlays and overlay.conf</title>
<body>
<p>
For this tutorial, we'll use GNAP to produce a bootable Firewall LiveCD that
will filter traffic and do NAT for a small LAN. We'll need to activate these
features in <e>overlay.conf</e> and overlay files for the network and firewall
configuration.
</p>
<note>
You don't need root rights to produce a GNAP LiveCD.
</note>
<p>
First of all, create a directory that will serve as the root for the overlay
directory, and create the <path>etc/</path>, <path>etc/conf.d/</path> and
<path>etc/firehol/</path> subdirectories:
</p>
<pre caption="Preparing overlay directories">
$ mkdir myoverlay
$ mkdir myoverlay/etc
$ mkdir myoverlay/etc/conf.d
$ mkdir myoverlay/etc/firehol
</pre>
<p>
Then we create the network configuration file (<path>etc/conf.d/net</path>),
for an external address of 111.222.111.47 (gateway 111.222.111.254) and a LAN
on 192.168.1.*. This file follows the Gentoo syntax described in the
<path>/etc/conf.d/net.example</path> file on your host system:
</p>
<pre caption="myoverlay/etc/conf.d/net contents">
# Use iproute2-style configuration
modules=( "iproute2" )
# The external interface
ipaddr_eth0=( "111.222.111.47/24" )
iproute_eth0=( "default via 111.222.111.254" )
# The internal interface
ipaddr_eth1=( "192.168.1.254/24" )
</pre>
<p>
Then we create the firehol configuration file that we'll use as a firewall,
allowing all traffic out of the LAN but no traffic in:
</p>
<pre caption="myoverlay/etc/firehol/firehol.conf contents">
version 5
interface eth0 internet
interface eth1 lan
router lan2internet inface eth1 outface eth0
masquerade
route all accept
</pre>
<p>
Finally, we need to write an <e>overlay.conf</e> file to tell GNAP that it
will use two network cards, and start a firehol firewall script at startup:
</p>
<pre caption="myoverlay/etc/overlay.conf contents">
# Use two network cards
NBCARDS=2
# Start the 'firehol' firewall script at startup
USE_FW=yes
FW_TYPE=firehol
</pre>
</body>
</section>
<section>
<title>Generating the .iso file, burning it to CD-R</title>
<body>
<p>
The next step is to use <c>gnap_overlay</c> to combine the
<path>myoverlay</path> overlay directory and the GNAP core to produce a
myfirewall.iso file containing the target LiveCD image. This is done using
the command:
</p>
<pre caption="Creating the .iso file">
$ gnap_overlay -i myfirewall.iso -o myoverlay/
</pre>
<p>
You should burn the resulting myfirewall.iso image onto a CD-R (or better, a
CD-RW) using your favorite CD burning tool, for example:
</p>
<pre caption="Burning the .iso file, YMMV">
$ cdrecord -v -eject speed=4 dev=/dev/hdc myfirewall.iso
</pre>
</body>
</section>
<section>
<title>Testing the resulting GNAP system</title>
<body>
<p>
Once the CD-R is ready, take it to the target system and use it to boot.
Low-end systems are OK, GNAP should boot successfully on 486 systems with as
low as 32 Mb RAM.
</p>
<note>
The BIOS of the target system should of course be configured to boot on CD-ROM.
</note>
<p>
During boot, you can see the GNAP-specific messages, while the GNAP initscript
(found as <path>/etc/init.d/overlay</path> on the target system) takes care of
overlaying files and processing the <e>overlay.conf</e> options.
If the configuration is not OK, you can change the contents of your
<path>myoverlay/</path> directory, rebuild an .iso image, burn it again, and
restart the target system with the new LiveCD.
</p>
</body>
</section>
</chapter>
<chapter>
<title>More customization</title>
<section>
<title>Overlay maintenance</title>
<body>
<p>
In the previous section, we used a single overlay source (the
<path>myoverlay/</path> directory), making it difficult to manage multiple
system configurations which share common features. <c>gnap_overlay</c> accepts
multiple <c>-o</c> options, so you can use multiple directories and
<e>conflet</e> files to form a single configuration:
</p>
<pre caption="Using multiple overlay sources">
$ gnap_overlay -i myfirewall.iso -o common/ -o specific/ -o mypublickey.tbz2
</pre>
<p>
Rather than including an <path>etc/overlay.conf</path> file in one of your
overlay sources, it is possible to specify the name of a file to use as
<e>overlay.conf</e> in your GNAP system, using the <c>-c</c> option:
</p>
<pre caption="Using a separate overlay.conf file">
$ gnap_overlay -i myfirewall.iso -c firewall.conf -o overlay2/
</pre>
<p>
To keep track of configuration changes, it is possible to use CVS directly
on the overlay directories. <c>gnap_overlay</c> will automatically ignore
the CVS control directories and not copy them onto the target system.
</p>
</body>
</section>
<section>
<title>Internationalization</title>
<body>
<p>
Two options in <e>overlay.conf</e> control the timezone (default being
UTC) and the keymap (default being 'us' keyboard layout) used on the target
system:
</p>
<ul>
<li>TIMEZONE: If you want to use another timezone than UTC, you should check
<uri link="http://leaf.sourceforge.net/doc/guide/buci-tz.html">this page</uri>
to determine the appropriate uclibc-compliant timezone code.</li>
<li>KEYMAP: If you want to log on locally, you might need to change the default
keyboard layout ('us') to something more appropriate. There is a complete
tree of keymaps in /usr/share/keymaps to choose from.</li>
</ul>
<pre caption="overlay.conf internationalization options example">
# Use Central European Time (UTC+1) with usual Summer Time rules
TIMEZONE=CET-1CEST
# Use a french keyboard layout
KEYMAP=fr
</pre>
</body>
</section>
<section>
<title>Network configuration</title>
<body>
<p>
We already know about the NBCARDS option in <e>overlay.conf</e>, which
specifies how many network cards should be started, and that we need to provide
an <path>etc/conf.d/net</path> file in our overlays to give the static network
configuration details. Here are the other options and typical overlay files
that you can use in further detailing the network configuration:
</p>
<ul>
<li>IP_RELAY: Should be set to yes if you want to relay IP between your network
interfaces. Useful if you want to run a gateway without a firewall
script.</li>
<li>NTPSERVER: Allows to specify the name of an NTP server to use as a time
source to maintain correct time on the target system.</li>
<li>USE_PPPOE: Indicates that the rp-pppoe should be started during boot.</li>
<li><path>etc/resolv.conf</path>: This file should contain the DNS
configuration for the system.</li>
<li><path>etc/hosts</path>: Complementary or alternatively to
<path>etc/resolv.conf</path>, this file will contain static hostnames
resolution information.</li>
<li><path>etc/conf.d/hostname</path>: This file can be specified to give a
specific hostname to the target. The <path>etc/hosts</path> file should be
adapted accordingly.</li>
</ul>
<note>
If you don't specify an <path>etc/conf.d/net</path> configuration, the system
will use DHCP to get the network configuration for the missing interfaces.
</note>
</body>
</section>
<section>
<title>Firewall, traffic control</title>
<body>
<p>
Enabling a firewall script is controlled by the USE_FW=yes option. By default,
GNAP will use <uri link="http://www.shorewall.net/">Shorewall</uri>, an
excellent and very complete iptables helper. You can set the FW_TYPE=firehol
option to switch to <uri link="http://firehol.sourceforge.net/">Firehol</uri>,
a simpler yet efficient script.
</p>
<p>
If you use Shorewall, you should overlay files in the <path>etc/shorewall</path>
directory to customize its behavior, in particular you should have to change
the <path>interfaces</path>, <path>zones</path>, <path>policy</path> and
<path>shorewall.conf</path> files. If you decide to use Firehol, you'll have
to customize the <path>etc/firehol/firehol.conf</path> file.
</p>
<p>
You can enable a traffic control script using the USE_TC=yes option. By default,
GNAP will use <uri link="http://sourceforge.net/projects/cbqinit">cbqinit</uri>,
a simple but sometimes inefficient traffic control helper. You can set the
TC_TYPE=htbinit option to switch to
<uri link="http://sourceforge.net/projects/htbinit">htbinit</uri>,
a more complex but more efficient script.
</p>
<p>
If you use cbqinit, you should overlay files in the <path>etc/cbqinit</path>
directory to customize its behavior, following the instructions given in
<path>/usr/sbin/cbqinit</path>. If you decide to use htbinit, you'll have
to create files in <path>etc/htbinit</path> following the instructions given
in <path>/usr/sbin/htbinit</path>.
</p>
</body>
</section>
<section>
<title>GNAP services</title>
<body>
<p>
GNAP offers several standard services. The first is the
<uri link="http://matt.ucc.asn.au/dropbear/dropbear.html">Dropbear</uri>
SSH server, which allows remote control of the GNAP system.
You enable it using the USE_SSH=yes option. Dropbear behaviour is
controlled using the <path>etc/conf.d/dropbear</path> file. You might
want to overlay prebuilt RSA/DSS keys for the server in
<path>etc/dropbear</path> (so that they are not rebuilt after each boot).
</p>
<p>
Another service is the
<uri link="http://thekelleys.org.uk/dnsmasq/doc.html">DnsMasq</uri>
DNS cache / DHCP server, which provides DNS resolution and DHCP
capabilities to a LAN. You enable it using the USE_DNSDHCP=yes option, and
you configure it through the <path>etc/dnsmasq.conf</path> file.
</p>
<p>
Another service that GNAP provides by default is the
<uri link="http://openvpn.net/">OpenVPN</uri> VPN solution. This is a simple
but full-featured VPN solution that will help you securely bridge LANs over
insecure networks. You enable it using the USE_VPN=yes option, in which case
you should overlay files in the <path>etc/openvpn</path> directory
with the desired OpenVPN configuration.
</p>
<p>
Finally, you can specify extra services to start when GNAP is booted.
There are two ways to do this: using the START_SERVICES option in
<e>overlay.conf</e> or using the <path>etc/gnap/start_services</path>
file:
</p>
<pre caption="Specifying the iptables and boa services using overlay.conf">
# Start iptables and boa at startup
START_SERVICES="iptables boa"
</pre>
<pre caption="etc/gnap/start_services contents, will start iptables and boa">
iptables boa
</pre>
</body>
</section>
<section>
<title>Accounts and passwords</title>
<body>
<p>
GNAP runs happily as a blackbox appliance by default. However, you might want
to be able to log onto it. By default, it doesn't define user accounts, and the
root account has an impossible password, making it impossible to log in. There
are several ways to change this behaviour:
</p>
<p>
You can set an empty root password, useful in test configurations for example,
using the EMPTY_ROOTPASS=yes option.
</p>
<p>
The most secure way to access the GNAP box is to run the Dropbear SSH server
in public key mode. You will need to configure Dropbear to disable password
logins (in <path>etc/conf.d/dropbear</path>) and put your own public key
to the <path>root/.ssh/authorized_keys</path> file:
</p>
<pre caption="etc/conf.d/dropbear contents to disable password auth">
DROPBEAR_OPTS="-s"
</pre>
<note>
The <path>/usr/lib/gnap/examples/conflets/dropbear_nopasswd.tbz2</path> file,
installed during the GNAP installation, is a conflet file containing
the necessary <path>etc/conf.d/dropbear</path> overlay file.
</note>
<p>
If you still want to change passwords for system users, you can do it by
overlaying a <path>etc/gnap/chpasswd</path> file containing
username:cryptedpassword lines that will be fed to <c>chpasswd -e</c> during
boot. See <c>man chpasswd</c> for details on the format of that file.
</p>
</body>
</section>
<section>
<title>Support for saving live configuration changes</title>
<body>
<p>
One problem you will have with GNAP systems using evolving configurations
(like firewalls) is that all live config changes will be lost at the next
reboot. One solution is to report all changes to the host system overlay
directories and be sure to burn a new CD-R with the new configuration before
the next reboot, but it's not very practical. Another solution is to use a
read/write partition and use the RW_SYNC system to backup the changes and
have them taken into account at next reboot automatically.
</p>
<p>
To enable this system, you should add the RW_SYNC option to your
<e>overlay.conf</e> file, pointing to the r/w partition you want to use.
GNAP supports FAT and ext2 partitions:
</p>
<pre caption="RW_SYNC value to backup to floppy disk">
RW_SYNC=/dev/fd0
</pre>
<p>
During the first boot, when the option is activated but no backup file is
present on the RW_SYNC partition yet, you'll get the following error during
the target system boot, which you can safely ignore:
</p>
<pre caption="First-time RW_SYNC safe errors">
* Sync rw-sync changes to /dev/fd0 ...
* Missing gnap_sav.tgz or gnap_md5.sum file : aborting [ !! ]
</pre>
<p>
Once the RW_SYNC option is enabled, you can use the <c>rw-sync.sh</c> utility
on the GNAP target system to specify which files to save. You only need to
specify the files once so that they are added to the rw-sync.cfg file for
subsequent backups.
</p>
<impo>
Don't forget to add the <path>/etc/rw-sync.cfg</path> file to the backup list
so that it is restored at next reboot !
</impo>
<pre caption="Specifying files and directories to backup">
# rw-sync.sh -a /etc/rw-sync.cfg
# rw-sync.sh -a /etc/shorewall/
</pre>
<p>
Then you can backup the files anytime after a change using the following
command:
</p>
<pre caption="Backup to the r/w partition">
# rw-sync.sh -w
</pre>
<p>
For more help on <c>rw-sync.sh</c>, just run it without any option to show
the help contents.
</p>
</body>
</section>
</chapter>
<chapter>
<title>Disk output</title>
<section>
<title>Objectives and requirements</title>
<body>
<p>
In the previous chapters, we used GNAP to produce a bootable LiveCD with
a customized network appliance system on it. We can also use GNAP to
initialize a disk device with a customized network appliance filesystem,
ready to be plugged in a target system and booted.
</p>
<p>
This mode of operation can be used to initialize hard disks that can be
plugged in low-end systems, but is especially useful for small device
targets like <uri link="http://www.soekris.com/">Soekris boxes</uri>
which can boot from a CompactFlash card, or other embedded systems
that will boot from an IDE bus (Disk-On-Module, Disk-On-Chip...).
</p>
<p>
For this mode of operation, you'll need to run <c>gnap_overlay</c> with
root rights to be able to manipulate the disk device at low-level. It is
also slightly more complicated and dangerous to run, so use at your own
risk !
</p>
</body>
</section>
<section>
<title>Media preparation</title>
<body>
<p>
Before you run <c>gnap_overlay</c> for the first time on a device, you need
to prepare the target media. You should plug the hard disk, CF card or other
medium you want to use on the host system and determine what is the plugged
device's name (system log might be useful here). You don't need to mount it !
For the remaining examples we'll suppose the target disk is available on
the host system as <path>/dev/sdb</path>.
</p>
<p>
If not already done, you need to partition the device. The partition where
GNAP will install the filesystem should be marked "active" and be large
enough to handle GNAP. In doubt, create a single partition of 16Mb,
and activate it.
</p>
<pre caption="Partitioning the /dev/sdb target disk">
# fdisk /dev/sdb
</pre>
<p>
The disk should also have a Master Boot Record installed, which will allow the
system to boot on it. If you're unsure, you can install an MBR using the
following command:
</p>
<pre caption="Installing MBR on /dev/sdb target disk">
# dd if=/usr/lib/gnap/mbr/mbr.bin of=/dev/sdb bs=512 count=1
</pre>
<note>
You only need to prepare the media once, you can run multiple
<c>gnap_overlay</c> commands on it once it has been prepared.
</note>
</body>
</section>
<section>
<title>Using gnap_overlay to write to disk</title>
<body>
<p>
In disk mode, you need to pass two options to <c>gnap_overlay</c>. One is
the complete name of the target disk partition <e>as seen on the host
system</e> (option <c>-d</c>), the other is the short name of the
target disk partition <e>as seen on the target system at boot</e> (option
<c>-r</c>). The distinction being quite important, here is an example.
</p>
<p>
Let's say you want to install a GNAP system on a CF card, to use to boot a
Soekris box. You plug it in the host system (the one you will run
<c>gnap_overlay</c> on), it is recognized as <path>/dev/sdb</path>.
You create a single partition on it, <path>/dev/sdb1</path>. So in this
example, the complete name of the target disk partition <e>as seen on the
host system</e> is <c>/dev/sdb1</c>.
</p>
<p>
On the other hand, you know, from testing or specs, that the Soekris box will
recognize a CF card plugged in it as <path>/dev/hda</path>. So the short name
of the target disk partition <e>as seen on the target system at boot</e>
is "hda1".
</p>
<p>
To initialize a disk with a GNAP configuration, you just have to replace the
<c>-i</c> option (used to build a LiveCD iso file) by the correct <c>-d</c>
and <c>-r</c> options:
</p>
<pre caption="Initializing the /dev/sdb1 partition">
# gnap_overlay -d /dev/sdb1 -r hda1 -o myoverlay/
</pre>
<note>
The target disk partition (<c>-d</c> option) should not be mounted.
<c>gnap_overlay</c> will mount it when it needs it.
</note>
</body>
</section>
<section>
<title>Specific options</title>
<body>
<p>
Two options might be useful in an embedded target situation. One is the
<c>-m</c> optional parameter you can use to tell GNAP to cache in memory the
filesystem once at startup to avoid multiple read access that can wear the
device (or be too slow).
</p>
<p>
The other is the <c>-s</c> parameter you can use
to tell GNAP to send the console to the serial port, at the specified baudrate.
This is especially useful for serial-port only devices like the Soekris boxes.
</p>
<pre caption="Reduce read access and use a 19200 baud serial console">
# gnap_overlay -d /dev/sdb1 -r hda1 -o myoverlay/ -m -s 19200
</pre>
</body>
</section>
<section>
<title>Writing to disk image files</title>
<body>
<p>
You might want to write to a disk image file rather than writing directly
a disk. This is made possible by the <c>-l</c> option: it allows to specify
the name of the disk image file to write to. Options from disk mode (except
the <c>-d</c> option) apply to image mode.
</p>
<pre caption="Write to the preexisting myimagefile.img disk image file">
# gnap_overlay -l myimagefile.img -r hda1 -o myoverlay/ -m -s 19200
</pre>
<warn>
Only one partition is supported on the disk image file !
</warn>
<p>
Alternatively you can ask GNAP to create the disk image file using the
<c>-L</c> option. The image file is by default 15 Mb long, you can specify an
alternative size using the <c>-S</c> option:
</p>
<pre caption="Write to a new disk image file named newimagefile.img">
# gnap_overlay -L newimagefile.img -S 14 -r hda1 -o myoverlay/
</pre>
</body>
</section>
</chapter>
<chapter>
<title>Using extensions</title>
<section>
<title>Extensions and remastering</title>
<body>
<p>
You might want to add features to your GNAP network appliance system. The
simplest way to do it is to use <e>extensions</e>, which are small software
packages adding functionality to a GNAP system.
</p>
<p>
Extensions are <path>.tar.bz2</path> compressed files with standardized names.
They are installed in standard in <path>/usr/lib/gnap/extensions</path> and
are named <path>gnapext_[name].tbz2</path>.
The <e>boa</e> extension, for example, is in fact
the <path>/usr/lib/gnap/extensions/gnapext_boa.tbz2</path> file.
</p>
<p>
The <c>gnap_remaster</c> tool combines a GNAP base filesystem file, an
existing GNAP core file and extensions to create a new GNAP core file which
will contain the extensions you choose. Then, you can use this extended GNAP
core file with <c>gnap_overlay</c> to create specific systems making use of
the extra functionality.
</p>
<figure link="gnap_remaster.png" short="gnap_remaster principle"
caption="How gnap_remaster works"/>
</body>
</section>
<section>
<title>Installing the GNAP extension package</title>
<body>
<p>
The GNAP extension package, which installs the <c>gnap_remaster</c> tool,
the GNAP basefs file and standard extensions (everything needed to play with
extensions), is available through Portage. You should install the version
corresponding to your GNAP package version.
</p>
<pre caption="GNAP extension package installation">
# emerge gnap-ext
</pre>
<warn>
gnap-ext might only be available in "~x86". Adjust your
<path>/etc/portage/package.keywords</path> file if needed.
</warn>
<note>
This will fetch a GNAP basefs file, which is usually quite large (~9Mb). You
can set the "minimal" USE flag if you don't want to download the basefs and
the standard extension pack, but only install the <c>gnap_remaster</c> tool.
</note>
</body>
</section>
<section>
<title>Remastering a GNAP core with extensions</title>
<body>
<p>
You should call <c>gnap_remaster</c> with the needed extensions names, as root.
This will build a mynewcore.tar remastered core file with the requested
extensions added:
</p>
<pre caption="Remastering the current GNAP core, adding the boa extension">
# gnap_remaster -e boa -o mynewcore.tar
</pre>
<note>
You must use the extensions <e>name</e>, not the filename. You can use multiple
<c>-e</c> options at the same time.
</note>
</body>
</section>
<section>
<title>Using gnap_overlay on a specific GNAP core</title>
<body>
<p>
It's easy to make <c>gnap_overlay</c> use your remastered core file instead
of the standard one. Just use the <c>-g</c> option:
</p>
<pre caption="Make gnap_overlay use the remastered core file">
$ gnap_overlay -g mynewcore.tar -i myfirewall.iso -o myoverlay/
</pre>
<note>
<c>gnap_remaster</c> can also be used on modules you build yourself:
extensions, minkernpackages and modulespackages. Please see the
<uri link="gnap-advancedguide.xml">GNAP Advanced User Guide</uri>
for more information about these features.
</note>
</body>
</section>
</chapter>
<chapter>
<title>GNAP Reference</title>
<section>
<title>overlay.conf</title>
<body>
<table>
<tr>
<th>Option</th>
<th>Values</th>
<th>Default</th>
</tr>
<tr>
<ti>EMPTY_ROOTPASS</ti>
<ti>If set to yes, the root password will be empty and everyone with
console access will be able to log as root. This should be used
mainly for testing purposes.</ti>
<ti><c>no</c></ti>
</tr>
<tr>
<ti>FW_TYPE</ti>
<ti>Set to <c>shorewall</c> or <c>firehol</c> depending on the firewall
system you want to use.</ti>
<ti><c>shorewall</c></ti>
</tr>
<tr>
<ti>IP_RELAY</ti>
<ti>Should IP relaying be active at startup ?</ti>
<ti><c>no</c></ti>
</tr>
<tr>
<ti>KEYMAP</ti>
<ti>Console keymap value.</ti>
<ti><c>us</c></ti>
</tr>
<tr>
<ti>NBCARDS</ti>
<ti>Number of connected network cards you want to start.</ti>
<ti><c>1</c></ti>
</tr>
<tr>
<ti>NTPSERVER</ti>
<ti>The name of the NTP server to use as a time synchronisation source.</ti>
<ti>empty (do not synchronise time using NTP)</ti>
</tr>
<tr>
<ti>RW_SYNC</ti>
<ti>Location of a read/write partition to use to save the modified
configuration files using rw_sync.sh</ti>
<ti>empty (do not use the RW_SYNC backup system)</ti>
</tr>
<tr>
<ti>START_SERVICES</ti>
<ti>List of the extra services you want to run as startup. This is
useful to start services from extensions (like boa).</ti>
<ti>empty (no extra service)</ti>
</tr>
<tr>
<ti>TC_TYPE</ti>
<ti>Set to <c>cbqinit</c> or <c>htbinit</c> depending on the traffic
control system you want to use.</ti>
<ti><c>cbqinit</c></ti>
</tr>
<tr>
<ti>TIMEZONE</ti>
<ti>The <uri link="http://leaf.sourceforge.net/doc/guide/buci-tz.html">uclibc-compliant timezone code</uri>.</ti>
<ti>empty (UTC)</ti>
</tr>
<tr>
<ti>USE_DNSDHCP</ti>
<ti>Set to <c>yes</c> to have the DNSMasq daemon run at startup.</ti>
<ti><c>no</c> (do not run)</ti>
</tr>
<tr>
<ti>USE_FW</ti>
<ti>Set to <c>yes</c> to have a firewall script run at startup.
See FW_TYPE option.</ti>
<ti><c>no</c> (do not run)</ti>
</tr>
<tr>
<ti>USE_PPPOE</ti>
<ti>Set to <c>yes</c> to have the rp-pppoe daemon run at startup.</ti>
<ti><c>no</c> (do not run)</ti>
</tr>
<tr>
<ti>USE_SSH</ti>
<ti>Set to <c>yes</c> to have the Dropbear daemon run at startup.</ti>
<ti><c>no</c> (do not run)</ti>
</tr>
<tr>
<ti>USE_TC</ti>
<ti>Set to <c>yes</c> to have a traffic control script run at startup.
See the TC_TYPE option.</ti>
<ti><c>no</c> (do not run)</ti>
</tr>
<tr>
<ti>USE_VPN</ti>
<ti>Set to <c>yes</c> to have the OpenVPN daemon run at startup.</ti>
<ti><c>no</c> (do not run)</ti>
</tr>
</table>
</body>
</section>
<section>
<title>GNAP-specific files to overlay on target system</title>
<body>
<p>
Other than <path>etc/overlay.conf</path>, GNAP uses several additional files
on the target system, here is their list:
</p>
<table>
<tr>
<th>Overlay file</th>
<th>Purpose</th>
<th>Example contents</th>
</tr>
<tr>
<ti><path>etc/rw_sync.conf</path></ti>
<ti>This is the rw_sync.sh control file, listing the files and directories
that should be backed up. You should probably use rw_sync.sh to edit
its contents.</ti>
<ti></ti>
</tr>
<tr>
<ti><path>etc/gnap/start_services</path></ti>
<ti>Contains a list of (whitespace-separated) service names that the target
system should additionally start at boot. Those services must exist as
<path>/etc/init.d</path> scripts on the target system !</ti>
<ti><c>iptables</c></ti>
</tr>
<tr>
<ti><path>etc/gnap/chpasswd</path></ti>
<ti>Contains a file that will be fed to <c>chpasswd -e</c> at boot to
initialize passwords on the system. It should contain a list of
username:cryptedpassword lines.</ti>
<ti><c>root:$1$o0YB.OW/$llYLxHFYX5DQrZF7FZicJ0</c></ti>
</tr>
</table>
</body>
</section>
<section>
<title>gnap_overlay and gnap_remaster options</title>
<body>
<p>
Please refer to the man pages for information on all the options available
in these commands:
</p>
<pre caption="getting more information about gnap_overlay or gnap_remaster">
$ man gnap_overlay
$ man gnap_remaster
</pre>
</body>
</section>
</chapter>
</guide>
|
GitWeb