Sentry Firewall CD(tm) Reference and Usage Guide <author>Stephen A. Zarkos, <url url="mailto:Obsid@Sentry.net" name="Obsid@Sentry.net"> <date>v0.7.0, 2004-08-30 <abstract> This document is designed to be a comprehensive reference and usage guide for the <url url="http://www.SentryFirewall.com/" name="Sentry Firewall CD">. This document in some cases covers some of the same material covered in the Sentry Firewall CD HOWTO and FAQ, but its primary purpose is as a reference and supplement to the other documentation available for the Sentry Firewall CD. </abstract> <toc>   <sect> Introduction This document is designed to be a more comprehensive reference guide to the Sentry Firewall CD. This is not designed to be a HOWTO, but instead to be a supplement to the HOWTO and the other available documentation. The following are some of the topics covered in this document: <itemize> <item> Available configuration directives and their usage. <item> Miscellaneous setup information for specific daemons or services. <item> Unique features of each branch. <item> Technical outline of the configuration scripts. </itemize> If you would like to add anything to this document, or if you have any questions or comments please feel free to email me, <url url="mailto:Obsid@Sentry.net?subject=HOWTO" name="Obsid@Sentry.net">. <newline> <sect1> Further Reading <itemize> <item> <url url="http://www.sentryfirewall.com/docs.html#howto" name="Sentry Firewall CD HOWTO"> <item> <url url="http://www.SentryFirewall.com/files/reference/" name="Sentry Firewall CD Reference Guide"> <item> <url url="http://www.sentryfirewall.com/FAQ.html" name="Sentry Firewall CD FAQ"> <item> <url url="http://www.sentryfirewall.com/contact.html#maillist" name="Mailing Lists"> </itemize> <newline> <sect1> Copyrights and Disclaimer The current copyright and disclaimer can be found on the website; <url url="http://www.SentryFirewall.com/files/COPYRIGHT">. It applies to the Sentry Firewall CD, and all the scripts and documentation associated with it.   <sect> Overview of Available Configuration Directives This section provides a general overview of the directives that are supported by all the Sentry Firewall CD branches. Since the "host" distribution varies with each branch, the configuration and initialization files used by each branch will vary. The branch-specific directives will be covered in later sections. <newline> <sect1> Replacing Files To replace a file that is supported by the configuration scripts, you may use the following syntax: <verb> filename_directive = /location/of/filename </verb> Where "filename_directive" is one of the directives supported by the configuration scripts. The file location can reference a file on a floppy disk(ie. /floppy/config/filename) or can also be in a URI format. The supported prefixed include "http://", "https://", "ftp://", "sftp://",and "scp://". For example: <verb> snort.conf = /floppy/snort.conf <or> snort.conf = scp://user:pass@<server>/config/snort.conf </verb> The current 'sentry.conf' file for each branch is available in the "/SENTRY/scripts/cd-config/" directory on the ISO, or on the website. The default sentry.conf file for each branch should contain all the directives currently supported. <newline> <sect1> Copying Files To replace files not supported by the configuration scripts, use the '|=' file copy directive. <verb> Syntax: source_file |= dest_file, OR dest_file = source_file Example: Copy file /floppy/daemon.conf to /etc/daemon.conf /floppy/daemon.conf |= /etc/daemon.conf <or> /etc/daemon.conf = /floppy/daemon.conf <or> /etc/daemon.conf = scp://<user>:<pass>@<server>/config/daemon.conf <or> scp://<user>:<pass>@<server>/config/daemon.conf |= /etc/daemon.conf </verb> <newline> <sect1> Making Symlinks Create a symlink <verb> Syntax: dest_file => source_file(where the symlink points to) Example: ## Make symlink called /etc/somefile.conf that points to /etc/otherfile.conf /etc/somefile.conf => /etc/otherfile.conf </verb> <newline> <sect1> Make a Directory. <bf>Note:</bf> The 'mkdir' directive is only available with the Sentry Firewall CD versions 1.5.0-rc14 or newer. <verb> Syntax: mkdir <PATH/DIRECTORY>[:MASK] </verb> Make a directory in the specified location with the specified permissions(MASK). MASK is optional and defaults to 0755(rwxr-xr-x). This directive can be useful if you want to copy files at boot-time to a directory that does not exist on the ramdisk by default. <newline> <sect1> 'device' Directive Set up an ethernet device to use during configuration. This device will only be used during configuration to grab files via http(s)/ftp/sftp/scp and is taken down after configuration is complete. <verb> device[1..10] = [device_name]:[driver_name]:[IP_Address]<|gateway> device[1..10] = [device_name]:[driver_name]:dhcp<|hostname> NOTES: 1) <hostname> and <gateway> are optional, but sometimes required. 2) Only one <gateway> can be declared, that is, you cannot set up more than one default gateway. *3) Devices set up with the 'device{1..10}' directive are TEMPORARY and are taken down after the configuration process is complete. See rc.inet1{.conf} for more permanent network setup. 4) Please see file: /SENTRY/scripts/cd-config/networking.pl for list of supported devices. Most 10/100BaseT ethernet devices should be supported. Examples: device1 = eth0:tulip:192.168.1.50|192.168.1.1 device2 = eth1:via-rhine:dhcp </verb> <newline> <sect1> 'nameserver' Directive Set up a nameserver to use during configuration. <verb> Syntax: nameserver = <DNS_IP> </verb> <newline> <sect1> Proxy Support Directives Set up a proxy for pulling files via http(s), or ftp. <verb> Syntax: http_proxy = http://<hostname>/ ftp_proxy = http://<hostname>/ proxy-user = <PROXY_USER> proxy-passwd = <PROXY_PASSWORD> </verb> <newline> <sect1> Passive FTP Support Use passive ftp instead of active ftp to retrieve files via ftp. <verb> Syntax: passive-ftp = <on|off> ## Default == off </verb> <newline> <sect1> 'include' Directive Retrieve and parse another 'sentry.conf' file. <verb> Syntax: include = </location/of/sentry.conf> Or, with network support - include=<ftp|http>://[<user>:<pass>@]<SERVER_IP></path/to/sentry.conf> </verb> <newline> <sect1> The 'path<#>' Directive. <bf>Note:</bf> The 'path<#>' directive is only available with the Sentry Firewall CD versions 1.5.0-rc13 or newer. Path statements tell the configuration scripts where to look for files. These can specify a path on a local or remote system. The variables "path1" to "path10" are allowed. <verb> Syntax: path<#> = <PATH> path<#> = <URI> </verb> <bf>NOTE:</bf> <URI> should point to a directory on a remote system, NOT just a file. <verb> Examples: path1 = /floppy/node1/config/ path2 = scp://user:pass@someserver/node123/config/ path3 = http://user:pass@someserver/node123-backup/config/ etc etc... </verb> You may then use the following syntax when declaring a file within your sentry.conf: <verb> Examples: squid.conf = squid.conf or /etc/someconf.conf = someconf.conf </verb> The configuration scripts will first look for "squid.conf" or "someconf.conf" in $m_point, which is usually /floppy. If it isn't found, then the system will try path1..path10 in order until "squid.conf" or "someconf.conf" is found. This not only makes for less typing when creating your sentry.conf, but it also allows you to add some redundancy to the configuration process. <newline> <sect1> 'cdrom' Directive Defines which device the CDROM is. If not declared the configuration scripts will still try to probe for and mount the CD. But declaring this is much easier/faster/safer. <verb> Syntax: cdrom = <DEVICE> Example: cdrom = /dev/hdc </verb> <newline> <sect1> 'cron' Directive Replace a user's crontab file. <verb> Syntax: cron:<USERNAME> = </LOCATION/OF/CRONTAB_FILE> </verb> <newline> <sect1> 'hostname' Directive Defines the hostname of the local machine. This directive can be used to either point to a file containing the hostname of the local machine, or to simply define the hostname itself. <verb> Syntax: hostname = </path/to/file> <or> hostname = MYHOSTNAME </verb> <newline> <sect1> The 'add_swap' directive <bf>Note:</bf> The 'add_swap' directive is only available with the Sentry Firewall CD versions 1.5.0-rc11 or newer. The 'add_swap' directive tells the configuration scripts to add a swap partition at configuration time. If the ":format" option is appended to the variable, then the configuration scripts will also format the partition before activating it. <bf>Warning:</bf> An improper setting of this variable could cause serious damage to data. <verb> Usage: add_swap = /dev/hda1 add_swap = /dev/hda1:format </verb> <newline> <sect1> The 'root_size' directive <bf>Note:</bf> The 'root_size' directive is only available with the Sentry Firewall CD versions 1.5.0-rc11 or newer. The 'root_size' directive allows one to change size of root(/) at configuration time(before any other files are copied). By default the root filesystem is around 18MB in size. This option allows you to change the size of the root filesystem if you need more/less space. Also - since root is mounted on a tmpfs filesystem - this area can be swapped out as needed. The suffix g, m, or k is accepted for binary kilo, mega and giga. If no suffix is added, a size in megabytes is presumed. <verb> Usage: root_size = "18M" </verb> The size of the root file system can also be changed after configuration by simply remounting it, ie "mount -oremount,size=24M /"   <sect> Directive Reference The following is a list of file directives currently supported by the various branches of the Sentry Firewall CD. Please note that this information is highly subject to change. Currently supported configuration directives can be found in the sample sentry.conf file available on the ISO image in the "SENTRY/scripts/cd-config" directory, or online at <url url="http://www.sentryfirewall.com/" name="http://www.SentryFirewall.com/">. <newline> <sect1> SENTRYCD(-DEVEL) Branches The following is a list of file directives currently supported in the SENTRYCD and SENTRYCD-DEVEL branches(slackware-based). Initialization scripts: <newline> <verb> rc.M Multiuser init script(runlevel 3). rc.6 Halt or reboot rc.dhcpd Startup script for ISC DHCP daemon. rc.netdevice Load modules for network devices(before rc.inet1 is run). rc.inet1 Set up ethernet interfaces. rc.inet1.conf Configuration file for rc.inet1. rc.inet2 Start network daemons. rc.inet2.conf Configuration file for rc.inet2. rc.keymap Load keyboard map. rc.local Local system init script. rc.modules Load any needed modules. rc.firewall Firewall script. rc.firewall.nat Nat-specific firewall script(not always used). rc.firewall.save Use if firewall script was generated using iptables-save. rc.ntpd ntpd initialization script. rc.sendmail Sendmail initialization script. rc.snort Snort initialization script. </verb> Important system configuration files: <newline> <verb> fstab fstab(5) ftpusers ftpusers(5) group group(5) hosts hosts(5) hosts.equiv hosts.equiv(5) hosts.allow hosts_access(5) hosts.deny hosts_access(5) inittab inittab modules.conf modules.conf(5) openssl.cnf OpenSSL configuration file. passwd passwd(5) profile bash(1) resolv.conf resolv.conf(5) shadow shadow(5) shells shells(5) </verb> Daemon configuration files: <newline> <verb> bgpd.conf Configuration file for bgpd(http://www.zebra.org/). dhcpd.conf Configuration file for dhcpd. dnsmasq.conf Configuration file for dnsmasq. httpd.conf Configuration file for Apache HTTP Daemon(http://www.apache.org/). inetd.conf Configuration file for inetd(8). ipsec.conf Configuration file for ipsec(http://www.freeswan.org/). ipsec.secrets IPSec secrets file for IKE/IPsec authentication. named.conf Configuration file for named(8). l2tpd.conf Configuration file for l2tpd, Layer 2 Tunnelling Protocol Daemon(http://www.l2tpd.org/) newsyslog.conf Configuration file for newsyslog. ospfd.conf Configuration file for ospfd(http://www.zebra.org/). portsentry.conf Configuration file for portsentry. pppoe.conf Configuration file for RP-PPPOE(http://www.roaringpenguin.com/pppoe/). pptpd.conf Configuration file for pptpd(http://poptop.lineo.com/). proftpd.conf Configuration file for proftpd(http://www.proftpd.net/). ntp.conf Configuration file for ntpd. rinetd.conf Configuration file for rinetd. ripd.conf Configuration file for ripd(http://www.zebra.org/). rndc.conf Configuration file for named control utility, rndc(8). sendmail.cf Configuration file for sendmail(http://www.sendmail.org/). smb.conf Configuration file for Samba(http://www.samba.org/). snort.conf Configuration file for snort(http://www.snort.org). squid.conf Configuration file for squid(http://www.squid-cache.org/). ss5.conf Configuration file for Socks Server 5(http://digilander.libero.it/matteo.ricchetti/) stunnel.conf Configuration file for stunnel(http://stunnel.mirt.net/). stunnel.pem Certificate chain PEM file for stunnel. syslog.conf syslogd(8) configuration file. syslog-ng.conf Configuration file for syslog-ng(http://www.balabit.com/products/syslog_ng/). vsftpd.conf Configuration file for vsftp daemon(http://vsftpd.beasts.org/). wlan.conf Configuration for prism based wireless cards(http://www.linux-wlan.com). gated.conf Configuration for GateD. ulogd.conf Configuration file for ulogd. zebra.conf Configuration file for zebra(http://www.zebra.org/). </verb> OpenSSH configuration files: <newline> <verb> ssh_config Configuration file for ssh(1). sshd_config Configuration file for sshd(8). shosts.equiv Like hosts.equiv(5) but for ssh. ssh_host_key Private rsa1 host key file. ssh_host_key.pub Private rsa1 host key file. ssh_host_dsa_key Private rsa1 host key file. ssh_host_dsa_key.pub Private rsa1 host key file. ssh_host_rsa_key Private rsa1 host key file. ssh_host_rsa_key.pub Private rsa1 host key file. ssh_known_hosts Public host keys of known ssh servers. ssh_known_hosts2 Public host keys of known ssh servers. </verb> Configuration directives for Webmin(http://www.Webmin.com/). <verb> start_webmin enable|disable Webmin. Default is "disable". webmin_config Main Webmin configuration file(/etc/webmin/config). miniserv.conf Config file for Webmin http(s) daemon. miniserv.pem SSL cert for Webmin http(s) daemon. An SSL cert will be created by rc.webmin if one is not specified. miniserv.users Password file used for Webmin. Default user:pass is sentry:SENTRY. NOTE: If this file is not replaced webmin will NOT start. </verb> Misc. configuration directives. <verb> cron:<user> Replace <user>'s crontab with specified file. add_swap Initialize a swap partition at configuration time. root_size Change the size of root(/) at configuration time. </verb> <newline> <sect1> SENTRYCD-DEB(-DEVEL) Branch Directives The following is a list of file directives currently supported in the SENTRYCD-DEB and SENTRYCD-DEB-DEVEL branches(debian-based). <bf> UNDER CONSTRUCTION </bf>   <newline> <sect> Configuration Reference This section contains general information about how to configure the Sentry Firewall CD, including information on which files to edit and how to setup specific daemons and services on a running system. More information about configuring specific daemons or services can be found in the <url url="http://www.SentryFirewall.com/files/HOWTO/" name="HOWTO">. <newline> <sect1> Init script configuration This section covers specifically the configuration of the system via the various init scripts kept in /etc/rc.d/(Slackware) or /etc/init.d/(Debian). <newline> <sect2> rc.inet1 and rc.inet1.conf <bf>NOTE:</bf> This section applies to the SENTRYCD and SENTRYCD-DEVEL(Slackware-based) branches. Versions of the Sentry Firewall CD before 1.5.0-rc7 utilized a perl-based rc.inet1 script to add and configure interfaces. The syntax of this file was similiar to the syntax used in the sentry.conf file for network configuration support - <tscreen><verb> $interface(1..10) = "<IF>:<IP ADDRESS[/NETMASK]>|<DHCP>" ## Examples: $interface1 = "eth0:192.168.1.1/24"; ## Set up eth0 with ip 192.168.1.1 and ## netmask 255.255.255.0. $interface2 = "eth0:192.168.1.2/24"; ## Bind second IP to eth0. $interface3 = "eth1:dhcp"; ## Use DHCP to set up eth1. </verb></tscreen> As you can see, the syntax is fairly simple. You can configure an interface or add an IP address by adding a "$interface#" variable. As of version 1.5.0-rc7, the Sentry Firewall CD utilizes a modified version of the rc.inet1 and rc.inet1.conf init files that appeared in Slackware 9.1. Once again, you alter the network setup by altering a bunch of variables, except this time you edit /etc/rc.d/rc.inet1.conf instead of rc.inet1 itself. By default, this file supports the setup of up to four ethernet devices. A basic entry to set up eth0 looks something like the following: <tscreen><verb> IPADDR[0]="192.168.1.10" NETMASK[0]="255.255.255.0" USE_DHCP[0]="" DHCP_HOSTNAME[0]="" ETH0_ALIAS[0]="" ## For multiple IPs on interface. ETH0_ALIAS[1]="" ## Ditto. GATEWAY="192.168.1.1" </verb></tscreen> To use DHCP instead of static IP addresses, set the "USE_DHCP[0]" directive to "yes". You may also add any number of additional "alias" IP addresses to each interface with the "ETHx_ALIAS[#]" variable. <bf>NOTE:</bf> Keep in mind that if neither of these rc files suit your needs you may simply replace the rc.inet1 file at boot time with your own script by using the 'rc.inet1' directive in your sentry.conf file. <newline> <sect1> Further Reading <itemize> <item> <url url="http://www.linux.org/docs/ldp/howto/HOWTO-INDEX/howtos.html" name="HOWTOs at Linux.org"> <item> <url url="http://www.freeswan.org/doc.html" name="FreeS/WAN Documentation"> <item> <url url="http://ebtables.sourceforge.net/documentation.html" name="Bridging Documentation"> <item> <url url="http://www.sentryfirewall.com/files/HOWTO/sentry-firewall-cd-howto-5.html" name="General Firewall Setup"> (Sentry Firewall CD HOWTO) <item> <url url="http://www.sentryfirewall.com/files/HOWTO/sentry-firewall-cd-howto-6.html" name="Snort Setup"> (Sentry Firewall CD HOWTO) <item> <url url="http://www.sentryfirewall.com/files/HOWTO/sentry-firewall-cd-howto-7.html" name="BIND Setup"> (Sentry Firewall CD HOWTO) | <url url="http://www.linux.org/docs/ldp/howto/DNS-HOWTO.html" name="DNS HOWTO"> </itemize> If there is something you wish to add to this list or to the documentation in general, please feel free to email <url url="mailto:Obsid@Sentry.net" name="Obsid@Sentry.net">.   <newline> <sect> The sentrycd(-devel) Branches This section contains information about features or directives that are unique to the SENTRYCD and SENTRYCD-DEVEL(slackware-based)branches. <bf> This section is still under construction. </bf>   <newline> <sect> The sentrycd-deb(-devel) Branches This section contains information about features or directives that are unique to the SENTRYCD and SENTRYCD-DEVEL(slackware-based)branches. <bf> This section is still under construction. </bf> <newline> <sect1> Start/Stop a Service or Daemon This directive gives you the ability to start or stop a service at bootup. The syntax looks like the following: <verb> service:[start|stop] = <path/to/service_init_file> </verb> For example: <verb> httpd:stop or httpd:start = /floppy/config/httpd </verb> In the above example, we are telling the Sentry Firewall CD to either start or stop the http daemon at bootup. The optional argument "<path/to/service_init_file>" is usually not necessary, but is used to actually replace the startup script located in /etc/rc.d/init.d/, in case you ever wanted to do so.   <newline> <sect> The Rootdisk <newline> <sect1> Overview A rootdisk is a gzip-compressed RAMdisk image that is mounted as root(/) during the boot process. Currently, the rootdisk for the Sentry Firewall CD is around 16-18 MB in size, uncompressed. It is, of course, possible to increase the size of the rootdisk to accommodate your needs. When you increase the size of this image you also need to increase the "ramdisk_size" parameter passed to the kernel at boot time by syslinux. This parameter can be adjusted either manually at the initial boot prompt or in the "isolinux.cfg" file kept in the isolinux directory on the CD. If the uncompressed ramdisk size is larger than this parameter, the boot process will not continue passed the loading of the kernel. That is, root(/) will never be mounted and you will get a kernel panic. As of version 1.5.0-rc11 the Sentry Firewall CD utilizes a tmpfs file system for its root partition. The tmpfs file system, also known as "virtual memory file system" or "shm fs", provides two major advantages: <itemize> <item> Tmpfs file systems reside in virtual memory, which means they can be swapped out. <item> Tmpfs file systems can be resized. </itemize> With this new development it is now possible to resize root(/) at configuration time(or any time afterward) without rebuilding the rootdisk or ISO. Please see the "root_size" and "add_swap" configuration directives for more details. <newline> <sect1> Creating the rootdisk I use a script called 'mkrootdsk.sh'. This is a bash shell script that formats/mounts the disk image, and then creates or copies the files to the disk image as needed. If you would like to attempt to use the mkrootdsk.sh script please be sure to read through it first, as it tends to be a bit hacky at times. It runs perfectly on my development system, but may not run well at all on yours. The output from the script should look something like the following: <tscreen><verb> Sentry Firewall CD-ROM: mkrootdsk.sh Copyright (C) Stephen A. Zarkos, Obsid@Sentry.net Ok, let's get to it... [+] Creating /root/rootdisk/root... Done. [+] Ok, starting to copy stuff to the rootdisk... [+] Making directories: root dev proc etc sbin bin lib mnt mnt1 mnt2 mnt3 mnt4 opt cdrom floppy tmp tmp/drivers var initrd... Done. [+] Copying /dev files... Done. [+] Working in /var... Done. [+] Working in /home... Done. [+] Working in /bin... Done. [+] Working in /sbin... Done. [+] Working in /lib... Done. [+] Working in /etc... Done. [+] Building drivers-2.4.tar.gz(network config support). [+] Using /cdrom/lib/modules/2.4.25GENERIC. [+] Tar/Gzipping /root/rootdisk/root... Done. [+] Zeroing out file: /root/rootdisk/initrd.img... Done. [+] Creating ext2 file system on /root/rootdisk/initrd.img... Done. [+] Mounting initrd.img on /root/rootdisk/mnt... Done. [+] Copying files to rootdisk... Done. [+] /root/rootdisk/initrd.img is still mounted, do you want me to unmount it? (y/n) y [+] Unmounting /root/rootdisk/mnt... Done. [+] Gzipping /root/rootdisk/initrd.img... Done. Location of new rootdisk --> /root/rootdisk/initrd.img </verb></tscreen> The finished ramdisk image is then copied to the isolinux directory before creating the actual ISO image. <newline> <sect1> Editing the rootdisk To look at and modify the initrd.img image, do something like the following: <tscreen><verb> blah@wherever:~$ cp /cdrom/isolinux/initrd.img /tmp/initrd.img.gz blah@wherever:~$ gzip -d /tmp/initrd.img.gz blah@wherever:~$ mount -o loop /tmp/initrd.img /MOUNT_POINT </verb></tscreen> You may then cd to /MOUNT_POINT and edit the files on the rootdisk. Once you are finished you can then unmount and gzip the initrd.img file and place it back in the isolinux directory. <newline> <sect1> Details of the rootdisk layout The following are some notes about the layout and design of the rootdisk. <itemize> <item> /usr is a symlink to /cdrom/usr. <item> Many of the standard system binaries on the system are symlinked to <url url="http://www.busybox.net/" name="busybox"> when possible. Few binaries actually reside on the rootdisk. <item> All the rest of the binaries in /bin /sbin are just symlinks to the /cdrom/{bin,sbin}. <item> Several libraries are present on the rootdisk. The exact libraries and versions may vary, please take a look at the mkrootdsk.sh script for those details. <item> /etc and /etc/rc.d are nearly empty at boot time. All the standard(default) system files are kept in /etc/default/*. The configuration scripts(perl) that are run at boot time will either take the files from the location specified in the configuration file(sentry.conf) or make symlinks to these default files from /etc/*. <item> The perl scripts are located on the rootdisk in either /etc/rc.d/SENTRY/ or /etc/init.d/SENTRY/. </itemize>   <sect> The Sentry Firewall Configuration Scripts This section is designed as a technical outline of the configuration scripts built for the Sentry Firewall CD. These configuration are responsible for finding and parsing the sentry.conf file and the directives contained therein. As of version 1.5.0-rc14 there are six configuration scripts overall on the system. These are kept in the "/etc/rc.d/SENTRY/" or the "/etc/init.d/SENTRY/" directory on the rootdisk. They are also available on the CD in the "<CDROM>/SENTRY/scripts/cd-config/" directory or online. The configuration scripts are called `cd-config.pl', `do_config.pl', `file_functions.pl', `get_config.pl', `networking.pl', and `process_conf.pl'. The details of these files are outlined below. <newline> <sect1> cd-config.pl This is the first perl script to run. It is usually called from the rc.S or rcS file, depending on the branch. This file contains the following: <itemize> <item> <bf>Mainline</bf> <newline> Starts by calling 'get_config()', then 'process_conf()' to process the config file and place the directives into the global %prefs hash. Then calls 'do_config()' to start the configuration process. <itemize> <item> <bf>Input:</bf> STDIN (yes|no), not always used. <item> <bf>Returns:</bf> Nothing. </itemize> <newline> <item> <bf>do_log()</bf> <newline> Takes as input a single string that will be written to a logfile($logfile). $logfile is '/var/log/SENTRY_LOG' by default. <itemize> <item> <bf>Input:</bf> $_[0] = string to print to log file. <item> <bf>Returns:</bf> 0 == fail, 1 == success. </itemize> </itemize> <newline> <sect1> get_config.pl This file contains the following: <itemize> <item> <bf>get_config()</bf> <newline> This function attempts to mount /dev/fd0 on /floppy, and if that fails it tries mounting /dev/hda1 on /mnt. If one of these succeeds it then looks for a configuration file(sentry.conf) and puts that in a global array called @conf. <itemize> <item> <bf>Input:</bf> $_[0] = name of configuration file. <item> <bf>Returns:</bf> 0 == fail, 1 == success. </itemize> <newline> <item> <bf>do_command()</bf> <newline> This function accepts a string that will be passed to the system to run as a command and a timeout(seconds) as input. It then attempts to run the command and timeout the operation once the "$timeout" has expired to avoid blocking. If a timeout value is not passed to the function "$timeout" is set to 10 seconds. Because of some of the oddities of this function, it may mangle "$_". If calling do_command() from a loop, try and use temporary variables instead of relying on $_. <itemize> <item> <bf>Input:</bf> $_[0] = Command to run, $_[1] = timeout(seconds). <item> <bf>Returns:</bf> 0 == fail, 1 == success, 2 == attempt timed out. </itemize> </itemize> <newline> <sect1> process_conf.pl This file contains the following: <itemize> <item> <bf>process_conf()</bf> <newline> This function parses the global array "@conf" and places it into global hash %prefs. It will also implement the "=>" and "|=" directives. <itemize> <item> <bf>Input:</bf> Nothing. <item> <bf>Returns:</bf> 0 == fail, 1 == success </itemize> <newline> <item> <bf>do_include()</bf> <newline> This function will attempt to retrieve file specified in the "include" configuration directive and shove it into "@conf". It will then call 'process_conf()' to take and parse the file. This process will continue until there are no more 'include' directives to parse. <itemize> <item> <bf>Input:</bf> Nothing. <item> <bf>Returns:</bf> 0 == fail, 1 == success </itemize> </itemize> <newline> <sect1> do_config.pl In general, this is the only configuration file you would need to modify if you would like to create a Sentry Firewall CD for any Linux distribution. This file contains the following: <itemize> <item> <bf>do_config()</bf> <newline> Parses configuration contained in @conf. Copies files specified in the configuration file and makes necessary symlinks in /etc. There are also a number of special configuration directives handled in this function such as `nameserver', `cdrom', `start_webmin', `add_swap', `root_size', etc. <newline><newline> <bf>%etc_vars</bf> replaces @etc_vars, @ssh_vars, and %specdir used in earlier versions of the configuration scripts. This hash contains all the files that are supported within sentry.conf, as well as their locations. For example, configuration directive `squid.conf' has a value of `/etc/squid'. Adding a new element to this list effectively adds a new directive that can be used within sentry.conf. <itemize> <item> <bf>Input:</bf> Nothing. <item> <bf>Returns:</bf> 0 == fail, 1 == success </itemize> <newline> <item> <bf>mount_cdrom()</bf> <newline> This function will attempt to mount the Sentry Firewall CD on /cdrom. Uses either what was defined with the "cdrom" directive in sentry.conf, or the information from `dmesg`. This was dealt with in rc.cdrom in older versions of the Sentry Firewall CD. <itemize> <item> <bf>Input:</bf> Nothing. <item> <bf>Returns:</bf> 0 == fail, 1 == success </itemize> <newline> <item> <bf>fix_modules()</bf> <newline> This function copies or symlinks the contents of "/cdrom/lib/modules/$kversion" to "/lib/modules/$kversion" unless the filename is 'TRANS.TBL'. 'TRANS.TBL' files are created when the ISO image was made and generally causes annoying errors with depmod. <itemize> <item> <bf>Input:</bf> Nothing. <item> <bf>Returns:</bf> 0 == fail, 1 == success </itemize> <newline> <item> <bf>recurse_dirs()</bf> <newline> This function recurses through /etc/default and fills @dirs with directory names. This can be an expensive operation, but it is useful when we start making symlinks from /etc/{dir} to /etc/default/{dir}. <itemize> <item> <bf>Input:</bf> $_[0] = Base path to start recursion. $_[1] = Base directory to start recursion. <item> <bf>Returns:</bf> Nothing. </itemize> <newline> <item> <bf>add_swap()</bf> <newline> This function initializes and adds a swap partition based on the 'add_swap' directive in the sentry.conf file. <itemize> <item> <bf>Input:</bf> Nothing <item> <bf>Returns:</bf> 0 == fail, 1 == success </itemize> <newline> <item> <bf>root_size()</bf> <newline> This function remounts root to change its size based on the 'root_size' directive in the sentry.conf file. <itemize> <item> <bf>Input:</bf> Nothing <item> <bf>Returns:</bf> 0 == fail, 1 == success </itemize> <newline> <item> <bf>nameserver()</bf> <newline> This function contains a block of code that was previously contained within do_config(), and was moved to its own function to make do_config() a bit easier to read. $prefs{'nameserver'} should contain an IP address for a DNS server which is written to /etc/resolv.conf. This directive is used primarily for network configuration support. <itemize> <item> <bf>Input:</bf> Nothing <item> <bf>Returns:</bf> 0 == fail, 1 == success </itemize> <newline> <item> <bf>no_shadow()</bf> <newline> no_shadow() contains a block of code that was previously contained within do_config(), and was moved to its own function to make do_config() a bit easier to read. This function deals specifically with $prefs{'shadow'}. If the `shadow' directive is not declared within sentry.conf, or if the file is not readable, then `/etc/ssh/sshd_config' and `/etc/inetd.conf' is replaced with a more strict default - essentially making it impossible to log in remotely with a default password. <itemize> <item> <bf>Input:</bf> Nothing <item> <bf>Returns:</bf> 0 == fail, 1 == success </itemize> <newline> <item> <bf>start_webmin()</bf> <newline> This function reads $prefs{'start_webmin'} to determine if it should allow webmin to start at boot time via rc.webmin. start_webmin() also checks to make sure the `miniserv.users' file was declared and is readable. If it is not readable, webmin will not be allowed to start, regardless of the value of $prefs{'start_webmin'}. Webmin can, of course, still be started manually later on. <itemize> <item> <bf>Input:</bf> Nothing <item> <bf>Returns:</bf> 0 == fail, 1 == success </itemize> <newline> <item> <bf>merge_fstab()</bf> <newline> This function contains the block of code that was previously contained within do_config(), and was moved to its own function to make do_config() a bit easier to read. Actually, it was originally called fix_fstab(), and then renamed and mostly rewritten as merge_fstab(). This function basically just checks the user-defined fstab file and makes sure it has at least the entries that are contained in `/etc/default/fstab'. <itemize> <item> <bf>Input:</bf> Nothing <item> <bf>Returns:</bf> 0 == fail, 1 == success </itemize> <newline> <item> <bf>merge_passwd()</bf> <newline> This function deals with the `shadow', `passwd', and `group' directives to make sure the user-defined files contain at least those that are contained within the system default. <itemize> <item> <bf>Input:</bf> $_[0] = `shadow', `passwd', or `group'. <item> <bf>Returns:</bf> 0 == fail, 1 == success </itemize> </itemize> <newline> <sect1> file_functions.pl This script contains a number of general functions that are used throughout the other configuration scripts. Most of the functions are related to working with files and directories. Some of these were contained in do_config.pl in earlier versions of the CD. <itemize> <item> <bf>create_dir()</bf> <newline> This function creates a specified directory. create_dir() is mainly utilized with the `mkdir' directive. <itemize> <item> <bf>Input:</bf> $_[0] = <PATH/DIRECTORY>[:MASK]. <item> <bf>Returns:</bf> 0 == fail, 1 == success. </itemize> <newline> <item> <bf>vrfy_file()</bf> <newline> vrfy_file() takes in one variable; a hash key name($var). This function verifies the existence of a file. If the path/filename exists as stated in the sentry.conf file, then the function returns 1. Otherwise vrfy_file() tries to find the file using the $m_point path and then passes $var onto locate_file() to try and locate the file using the $path{1..10} variables. <itemize> <item> <bf>Input:</bf> $_[0] = hash key name($var). <item> <bf>Returns:</bf> 0 == fail, 1 == success, 2 == syntax or misc. error. </itemize> <newline> <item> <bf>locate_file()</bf> <newline> locate_file() takes in one variable; a hash key name($var). This function attempts to locate the file using the $path{1..10} variables declared in sentry.conf. <itemize> <item> <bf>Input:</bf> $_[0] = hash key name($var). <item> <bf>Returns:</bf> 0 == fail, 1 == success. </itemize> <newline> <item> <bf>retr_file_net()</bf> <newline> Attempts to retrieve file if destination looks like a http(s)/(s)ftp/scp URI. Currently, only the `NOERR' option is supported which prevents retr_file_net() from logging errors. <itemize> <item> <bf>Input:</bf> $_[0] = URI/FILENAME to retrieve. $_[1] = Options. <item> <bf>Returns:</bf> 0 == fail, 1 == success. </itemize> <newline> <item> <bf>vrfy_path()</bf> <newline> Ensure the directory to the passed file exists. This function is often called before attempting to copy a file. <itemize> <item> <bf>Input:</bf> $_[0] = PATH/FILENAME <item> <bf>Returns:</bf> 0 == success. </itemize> <newline> <item> <bf>pcopy()</bf> <newline> Copies $src to $trg and creates target directory if needed. Options that can be passed to this function include `PERM', `LINK', `RECURS' which simply translate to the `-p', `-dp', and `-Rdp' options that are passed to `/bin/cp'. The default behavior is to pass no options to `/bin/cp'. <itemize> <item> <bf>Input:</bf> $_[0] = source file. $_[1] = destination file. $_[2] = options. <item> <bf>Returns:</bf> 0 == fail, 1 == success. </itemize> <newline> <item> <bf>do_log()</bf> <newline> Takes as input a single string that will be written to a logfile($logfile). $logfile is '/var/log/SENTRY_LOG' by default. <itemize> <item> <bf>Input:</bf> $_[0] = string to print to log file. <item> <bf>Returns:</bf> 0 == fail, 1 == success. </itemize> </itemize> <newline> <sect1> networking.pl This file contains the following: <itemize> <item> <bf>networking()</bf> <newline> This function utilizes the "device{1..10}" configuration directive to set up or take down an ethernet interface and set up a default gateway if necessary. <itemize> <item> <bf>Input:</bf> $_[0] = 1|NET_UP or 2|NET_DOWN, set up or take down networking. <item> <bf>Returns:</bf> 0 == fail, 1 == success, 2 == failed to initialize device or assign an IP address. </itemize> <newline> <item> <bf>retr_file()</bf> <newline> This function attempts to retrieve a file via http(s)/ftp/scp/sftp using wget or scp/sftp. <itemize> <item> <bf>Input:</bf> $_[0] = Filename to retrieve, $_[1] = Location of file(URI). <item> <bf>Returns:</bf> Returns 0 on failure, otherwise returns the local path/filename of the retrieved file. </itemize> <newline> <item> <bf>mk_batch()</bf> <newline> Function to create a batch file for use with sftp. Since sftp doesn't have a recursive -r option, we need to create a batch file to tell sftp to manually grab the stuff in the subdirectories under /etc/sysconfig. This is only used when dealing with the sysconf_dir directive, which is not valid in the "sentrycd" branch, but useful in other branches such as "sentrycd-rh" and may be useful in other Sentry Firewall based Linux distributions. <itemize> <item> <bf>Input:</bf> $_[0] = Remote path from where files should be retrieved. <item> <bf>Returns:</bf> 0 == fail, 1 == success </itemize> <newline> <item> <bf>remove_mods()</bf> <newline> This function uses 'rmmod' to remove any previously loaded ethernet driver modules for network configuration. Use the hash "%depend" to remove the module and its dependencies in the proper order. <itemize> <item> <bf>Input:</bf> $_[0] = Name of ethernet driver to remove. <item> <bf>Returns:</bf> 0 == fail, 1 == success </itemize> <newline> <item> <bf>load_mods()</bf> <newline> This function uses 'modprobe' to load ethernet driver modules for network configuration support. Uses the hash "%depend" to load the module and its dependencies in the proper order. <itemize> <item> <bf>Input:</bf> $_[0] = Name of ethernet driver to load. <item> <bf>Returns:</bf> 0 == fail, 1 == success </itemize> </itemize>  </article>