Shorewall Support Guide

Tom Eastep

Copyright © 2001-2007 Thomas M. Eastep

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover, and with no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”.

Important

Problem reports that do not include the information requested in the Problem Reporting Guidelines below will not be answered by the Shorewall author.

2008/03/12


Table of Contents

Before Reporting a Problem or Asking a Question
Problem Reporting Guidelines
Where to Send your Problem Report or to Ask for Help
Subscribing to the Users Mailing List
Subscribing to the Announce Mailing List
Subscribing to the Development Mailing List
Unsubscribing from Shorewall Mailing Lists
Other Mailing Lists

Caution

This article applies to Shorewall 3.0 and later. If you are running a version of Shorewall earlier than Shorewall 3.0.0 then please see the documentation for that release.

Before Reporting a Problem or Asking a Question

There are a number of sources of Shorewall information. Please try these before you post.

  • The three currently-supported Shorewall major releases are 3.2, 3.4 and 4.0.

    Note

    Shorewall versions earlier than 3.2.0 are no longer supported; we will try to help but I will personally not spend time reading earlier code to try to help you solve a problem and I will not release a patch to correct any defect found.

  • More than half of the questions posted on the support list have answers directly accessible from the Documentation Index

  • The FAQ has solutions to more than 50 common problems.

  • The Troubleshooting Information contains a number of tips to help you solve common problems.

  • The Shorewall Users Mailing List Archives are a good source of information.

Problem Reporting Guidelines

Please refer to the following flowchart to guide you through the problem reporting process. It will ensure that you provide us with the information we need to solve your problem as quickly as possible.

Important

Please don't use distribution specific programs like "service" or init scripts to start/restart Shorewall while trying to solve a problem, just follow carefully the instructions below.

Important

As a general matter, please do not edit the diagnostic information in an attempt to conceal your IP address, netmask, nameserver addresses, domain name, etc. These aren't secrets, and concealing them often misleads us (and 80% of the time, a cracker could derive them anyway from information contained in the SMTP headers of your post).

  1. If your problem is that an error occurs when you try to “shorewall start” or if Shorewall is otherwise failing to start properly, then please do the following.

    If your VERBOSITY setting in shorewall.conf is less than 2 and you are running the Shorewall-shell compiler, then try running with a higher verbosity level by using the "-vv" option:

    shorewall -vv [re]start

    That will give you additional progress messages that may make it clear which entry in which file is generating the error.

    If that didn't solve your problem, then please

    /sbin/shorewall trace start 2> /tmp/trace

    Forward the /tmp/trace file as an attachment compressed with gzip or bzip2 (If you are running Shorewall-perl, there is no need to compress the file — it will be very short).

    If you are running Shorewall version 3.2.0 or later and compilation succeeds but the compiled program fails, then please include the compiled program with your report. The compiled program will be named /var/lib/shorewall/.start if the command is shorewall start and it will be named /var/lib/shorewall/.restart if the command is shorewall restart.

    If you are running Shorewall-perl 4.0.5 or later, you may also include the word debug as the first argument to the /sbin/shorewall and /sbin/shorewall-lite commands.

    shorewall debug restart

    In most cases, debug is a synonym for trace. The exceptions are:

    • debug is ignored by the Shorewall-perl compiler.

    • debug causes altered behavior of scripts generated by the Shorewall-perl compiler. These scripts normally use iptables-restore to install the Netfilter ruleset but with debug, the commands normally passed to iptables-restore in its input file are passed individually to iptables. This is a diagnostic aid which allows identifying the individual command that is causing iptables-restore to fail; it should be used when iptables-restore fails when executing a COMMIT command.

    Warning

    The debug feature is strictly for problem analysis. When debug is used:

    1. The firewall is made 'wide open' before the rules are applied.

    2. The routestopped file is not consulted.

    3. The rules are applied in the canonical iptables-restore order. So if you need critical hosts to be always available during start/restart, you may not be able to use debug.

  2. If you are unsure if Shorewall is starting successfully or not then first note that if Shorewall starts successfully, the last message produced by Shorewall 3.0 is "Shorewall Started" and the last message produced by Shorewall 3.2 in "done.":

    Shorewall 3.0:

    …
Activating Rules...
Shorewall Started
gateway:~#

    Shorewall 3.2:

    …
Activating Rules...
done.
gateway:~#

    If you are seeing this message then Shorewall is starting successfully.

    If you are still unsure if Shorewall is starting or not, enter the following command:

    /sbin/shorewall status

    If Shorewall has started successfully, you will see output similar to this:

    Shorewall-3.0.6 Status at gateway - Thu Mar 30 14:07:29 PDT 2006

Shorewall is running
State:Started (Thu Mar 30 14:07:29 PDT 2006)

    If Shorewall has not started properly, you will see output similar to this:

    Shorewall-3.0.6 Status at gateway - Thu Mar 30 14:08:11 PDT 2006

Shorewall is stopped
State:Stopped (Thu Mar 30 14:08:11 PDT 2006)

    The "State:" refers to the Shorewall State Diagram.

  3. If Shorewall is starting successfully and your problem is that some set of connections to/from or through your firewall isn't working (examples: local systems can't access the internet, you can't send email through the firewall, you can't surf the web from the firewall, connections that you are certain should be rejected are mysterously accepted, etc.) or you are having problems with traffic shaping then please perform the following six steps:

    1. If Shorewall isn't started then /sbin/shorewall start. Otherwise /sbin/shorewall reset.

    2. Try making the connection that is failing.

    3. /sbin/shorewall dump > /tmp/status.txt

    4. Post the /tmp/status.txt file as an attachment compressed with gzip or bzip2.

    5. Describe where you are trying to make the connection from (IP address) and what host (IP address) you are trying to connect to.

  4. Otherwise:

    Shorewall is starting successfuly and you have no connection problems and you have no traffic shaping problems. Your problem is with performance, logging, etc. Please include the following:

    • the exact version of Shorewall you are running.

      /sbin/shorewall version

    • the complete exact output of

      ip addr show

    • the complete exact output of

      ip route show

    • A detailed description of your problem.

  • Please remember we only know what is posted in your message. Do not leave out any information that appears to be correct, or was mentioned in a previous post. There have been countless posts by people who were sure that some part of their configuration was correct when it actually contained a small error. We tend to be skeptics where detail is lacking.

  • Please keep in mind that you're asking for free technical support. Any help we offer is an act of generosity, not an obligation. Try to make it easy for us to help you. Follow good, courteous practices in writing and formatting your e-mail. Provide details that we need if you expect good answers. Exact quoting of error messages, log entries, command output, and other output is better than a paraphrase or summary.

  • Please give details about what doesn't work. Reports that say “I followed the directions and it didn't work” may elicit sympathy but probably little in the way of help. Again -- if ping from A to B fails, say so (and see below for information about reporting “ping” problems). If Computer B doesn't show up in “Network Neighborhood” then say so. If access by IP address works but by DNS names it doesn't then say so.

  • Please don't describe your environment and then ask us to send you custom configuration files. We're here to answer your questions but we can't do your job for you.

  • Please do NOT include the output of iptables -L — the output of shorewall show or shorewall dump is much more useful to us.

  • Do you see any “Shorewall” messages (“/sbin/shorewall show log”) when you exercise the function that is giving you problems? If so, include the message(s) in your post.

  • Please do not include Shorewall configuration files unless you have been specifically asked to do so. The output of shorewall dump collected as described above is much more useful.

  • The list server limits the size of posts to the lists, so don't post graphics of your network layout, etc. to the Mailing List -- your post will be rejected.

  • The author gratefully acknowleges that the above list was heavily plagiarized from the excellent LEAF document by Ray Olszewski found here.

Where to Send your Problem Report or to Ask for Help

If you haven't read the Problem Reporting Guidelines above, please read them now — Failure to supply the information that we need will just delay a solution to your problem.

If you run the current development release and your question involves a feature that is only available in the development release (see the Shorewall Release Model page) then please post your question or problem to the Shorewall Development Mailing List.

Otherwise, please post your question or problem report to the Shorewall users mailing list. If you wish to keep the details of your configuration private, then you may forward the accompanying dumps/traces etc. to [email protected]; the report itself should still go to the appropriate mailing list.

IMPORTANT: You must subscribe to the mailing lists before you will be able to post to them (see links below).

For quick questions, there is also a #shorewall channel at irc.freenode.net.

Subscribing to the Users Mailing List

To Subscribe to the users mailing list go to https://lists.sourceforge.net/lists/listinfo/shorewall-users.

Subscribing to the Announce Mailing List

To Subscribe to the announce mailing list (low-traffic,read only) go to:

https://lists.sourceforge.net/lists/listinfo/shorewall-announce

Subscribing to the Development Mailing List

To Subscribe to the development mailing list go to https://lists.sourceforge.net/lists/listinfo/shorewall-devel.

Unsubscribing from Shorewall Mailing Lists

If you are really dim-witted enough to have to ask -- you unsubscribe at the same place that you subscribed. Doh.......

Other Mailing Lists

For information on other Shorewall mailing lists, go to http://sourceforge.net/mail/?group_id=22587 .