Back to index

Configuration files

Templates

EasyWall uses XML templates to define the ports, protocols and kernel modules needed by each program. These templates are stored in /usr/share/easywall/xml (except the ones created by the user, which are stored at /etc/easywall/xml) and have the following structure:

<?xml version='1.0' encoding='UTF-8'?>
<easywall>
    <category>category</category>
    <unique-id>unique id for this program</unique-id>
    <name>Showed program name</name>
    [<name locale="xx_XX">Showed program name in locale xx_XX</name>]
    [<name locale= ...>]
    [<check-file>path to program's binary</check-file>]
    [<check-file ...>]
    [<module>Kernel module to load</module>]
    [<module ...>]
    <port [editable="yes/no"]>
        <type>tcp/udp/icmp</type>
        [<id>Port's unique ID</id>]
        <icmp_type>ICMP type value</icmp_type>
        [<icmp_code>ICMP code value</icmp_code>]
        <value>Port value</value>
        [<range>Port range</range>]
        [<base>Base port's unique ID</base>]
        [<port-name>Showed port name</port-name>]
        [<port-name locale="yy_YY">Showed port name in locale yy_YY</port-name>]
        [<port-name locale= ...>]
    </port>
    [<port ...>]
</easywall>

Category: is the cathegory where this program will be listed on. Only the following ones can be used:

There are two extra categories: user-defined, used only for templates created by the user, and other, where are included every template that doesn't use any of the former categories.

Unique-id defines an unique id for this template, to allow EasyWall to reference it. It must be a unique string (in the sense that each template must have a different unique id).

Name is the default name showed in the main window. It's mandatory to put one entry without the locale parameter, and is optional to add one or more entries with it. When the program is run, let's say, using locale xx_YY, it will search for the name entry with a locale parameter xx_YY. If EasyWall can't find it, will search an entry with a locale parameter xx. Finally, if still can't find it, it will show the default name entry.

Check-file allows to show a template only when a file is present in the hard disk. You can add as many tags as you want, and this template will be shown only when at least one of that files exists. If none exists, the entry will not be displayed. If there is no check-file tag, the entry will be displayed always.

Module allows to specify as many kernel modules as this program needs to be run. An example is the nf_conntrack_netbios_ns module, needed to work with Windows shared files and printers.

Port tag is used to define each port used by the program. The parameter editable specifies if this port can be edited by the user or not. Inside this tag can be these ones:

Type sets the port type, which can be TCP, UDP or ICMP. Depending on this value, you will have to add or not some of the next tags.

Id: this tag allows to specify an unique id for this port. Is mandatory when the port is editable, and not used when the port isn't editable. It must be unique inside each template file, but can be reused in different templates.

Icmp_type is a mandatory tag only when the type is ICMP. It defines the type value for the ICMP packets.

Icmp_code is an optional tag, only useful when the type is ICMP. When set, allows to specify the code value for ICMP packets. If it's not added, all ICMP packets with the former type will be allowed to enter.

Value is a mandatory tag only when the type is TCP or UDP. It contains the port number to open, or the offset (positive or negative) when the port has also a base tag.

Range is an optional tag that allows to open several consecutive ports. It contains how many ports, starting from the number set in the value tag, must be opened.

Base is an optional tag that allows to define the port number to open refered to another port, containing its unique id. An example is aMule, where you have to open three ports, but one is always three plus the value of a former one.

Port-name allows to use a personalized name for this port. You can add more tags with the locale parameter in order to allow translations to other languages.

Let's see some examples:

        <?xml version='1.0' encoding='UTF-8'?>
        <easywall>
            <category>chat</category>
            <unique-id>amsn</unique-id>
            <name>aMSN</name>
            <check-file>/usr/bin/amsn</check-file>
            <check-file>/usr/local/bin/amsn</check-file>
            <port editable="no">
                <type>tcp</type>
                <value>6890</value>
                <range>10</range>
            </port>
            <port editable="no">
                <type>udp</type>
                <value>6890</value>
                <range>10</range>
            </port>
        </easywall>

This is the template for aMSN. Here we assign it the chat category and amsn as unique id. In name we put a capitalized version. In check-file we put both /usr/bin/amsn and /usr/local/bin/amsn to ensure that this template is shown when the user has installed aMSN from a package or has compiled it by itself, but that it is not shown when is not present in the system.

Finally we define two sets of ports: the first one opens the TCP ports from 6890 to 6899, and the second one opens the UDP ports from 6890 to 6899.

        <?xml version='1.0' encoding='UTF-8'?>
        <easywall>
            <category>p2p</category>
            <unique-id>amule</unique-id>
            <name>Amule</name>
            <check-file>/usr/bin/amule</check-file>
            <check-file>/usr/local/bin/amule</check-file>
            <port editable="yes">
                <type>tcp</type>
                <id>sttcp</id>
                <value>4662</value>
                <port-name>Standard client TCP port</port-name>
                <port-name locale="es_ES">Puerto TCP estándar</port-name>
                <port-name locale="gl_ES">Porto do cliente TCP estándar</port-name>
            </port>
            <port editable="yes">
                <type>udp</type>
                <id>studp</id>
                <value>4672</value>
                <port-name>Extended client UDP port</port-name>
                <port-name locale="es_ES">Puerto UDP estándar</port-name>
                <port-name locale="gl_ES">Porto UDP extendido do cliente</port-name>
            </port>
            <port editable="no">
                <type>udp</type>
                <id>xtudp</id>
                <base>sttcp</base>
                <value>3</value>
                <port-name>UDP port for extended server requests</port-name>
                <port-name locale="es_ES">Puerto UDP para peticiones extendidas</port-name>
                <port-name locale="gl_ES">Porto UDP para peticións extendidas</port-name>
            </port>
        </easywall>

This template is for aMule. Here we can see that the first and second port entries are editable, and that's why they have an id tag. They also have a port-name tag, with its content matching the name used in aMule's configuration window. Finally, the third port is not editable, but contains a base tag which points to the first port (using its unique id). Since the value tag contains 3, that means that the value used for this port will be always the value of the first one plus three. This is: if the first port is the 8724, then the third port will be 8727. The user will not have to manually set its value.

An important note is that the unique ids for the ports must be unique only inside this template. This means that you can use the ids sttcp or studp in other templates.

        <?xml version='1.0' encoding='UTF-8'?>
        <easywall>
            <category>file_transfer</category>
            <unique-id>samba_client</unique-id>
            <name>Access to remote files and printer with SMB protocol</name>
            <name locale="es_ES">Acceder a ficheros e impresoras remotos en una red Windows</name>
            <name locale="gl_ES">Aceder a arquivos e impresoras remotas nunha rede Windows</name>
            <module>nf_conntrack_netbios_ns</module>
        </easywall>

This is the template to allow to access to remote SMB servers. Here there isn't a check-file tag, so this template will be shown always. Another new tag is the module one. Here we can see that it's used to load the nf_conntrack_netbios_ns module.

        <?xml version='1.0' encoding='UTF-8'?>
        <easywall>
            <category>icmp</category>
            <unique-id>ping</unique-id>
            <name>Answer PING</name>
            <port>
                <type>icmp</type>
                <icmp_type>8</icmp_type>
                <icmp_code>0</icmp_code>
            </port>
        </easywall>

Finally this is the template to allow PING requests to be answered. Here we define an ICMP port, allowing to enter the ICMP packets with a type value of 8 and a code of 0. If we remove teh code tag, all the ICMP packets with a type value of 8 would be accepted.

Configuration files

EasyWall uses several files to store the configuration, templates, and so on. These are the following:

ACTIVE.XML

This file contains the currently active programs. It's format is as follows:

        <easywall-active>
            <active unique-id="program's unique id" />
            [<active .../>]
        </easywall-active>

The unique-id parameter is the unique id used in the program's template. The programs whose unique id is in this file will be marked as active, and the other ones will be marked as inactive.

MODIFIERS.XML

This file contains the new values for each port modified by the user. It's format is as follows:

        <easywall-modifiers>
            <program unique-id="unique id">
                <port-modify range="range value" id="port's unique id" port="new port value" />
                [<port-modify .../>]
            </program>
            [<program unique-id ... >
        </easywall-modifiers>

Each program entry defines the modified ports for that program. Each port-modify entry contains the new value for the specified port. If the modified port is a single port, range must be 1; if it's a range of ports, it can be 1 or a greater value. If the port in the original template is marked as non-editable, the new value will be ignored.

TEMPLATE_BASE.XML

This file contains the original templates used to generate the firewall itself. EasyWall will use its contents to generate a BASH script that configures IPTables with the desired ports.

The format for this file is the following one:

                <?xml version='1.0' encoding='UTF-8'?>
                <easywall-templates>
                    <line>IPTables line for TCP/UDP ports</line>
                    <icmp>IPTables line for ICMP ports</icmp>
                    <module>Line for MODPROBE</module>
                    <base>Main template</base>
                </easywall-templates>

The default content for the IPTables line for TCP/UDP ports is $iptables -A INPUT -p [TYPE] -m [TYPE] --destination-port [PORT] -j ACCEPT. EasyWall replaces [TYPE] with TCP or UDP, and [PORT] with the port number to open.

The default content for the IPTables line for ICMP is $iptables -A INPUT -p icmp --icmp-type [TYPE] -j ACCEPT, EasyWall replaces [TYPE] by the port type, or type/code desired.

The default content for the Line for MODPROBE is $modprobe [NAME], and EasyWall replaces the [NAME] with the module name.

Finally, the base tag contains the base script for the firewall. There are two keywords: [MODULES_LINES], which is replaced by a list of modules to load (using the line for MODPROBE as template), and [IPTABLES_LINES], which is replaced by a list of iptables commands to open the desired ports, using the iptables line for TCP/UDP and for ICMP as template.

All these templates can be modified by the user in the program, and the new values are stored, with the same format, in a file called template.xml. The user can always return to the original templates just clicking in a button, because they are preserved in the template_base.xml file.

Back to index