Wiki for ASN_IPFire Script

Content

last edit: 2023-03-18

1 Usage

Output of asn_ipfire.sh --help :

Usage: asn_ipfire.sh [OPTION] [COMPANYs | -f FILE] [PARAMETER]
Add or remove networks to IPFire firewall Groups: Networks & Host Groups

IPFire-Mode options:
  -a, --add         Add new company networks
  -r, --remove      Remove company networks from customnetworks & customgroups

IPFire-Mode parameter:
  -l, --list        List of companies already added by this script
      --renumber    Renumber lines of customnetworks & customgroups
      --sort        Re-sort lines of customnetworks & customgroups
      --backup      Backup customnetworks & customgroups before change
      --rmbackup    Remove backup files of customnetworks & customgroups
      --restore     Restore customnetworks & customgroups from backup

Non-IPFire-Mode options:
      --network     Create output FILE with networks
      --asn         Create output FILE with ASNs only
      --custom      Create output FILE with custom rules

Common parameter:
  -c, --check          Check source for availability
  -f, --file FILE      Get company list from FILE
  -i, --interactive    Ask user before a file will be overwritten
  -k, --keep           Keep temporary source files after finish
  -o, --outfile FILE   Custom result file FILE (Non-IPFire-Mode)
      --raw            Networks not consolidated
      --iprange        Use iprange tool
  -v, --verbose        Verbose mode
  -V, --version        Show this script version and exit
  -h, --help           Show this help and exit

COMPANY to be one or more company names, put into double quotes ("...")
  Multi company names must be comma separated
  Substitute spaces with tilde (~)
  Restrict to exact matches with tilde (~) before and after the name
  Company names are handled case insensitive.
  example: asn_ipfire.sh --add "CompanyA,Company~NameB,~CompanyC~" 

FILE to be a name of a file, containing one or more company names.
  Company names to be separated by comma or line feed.
  examples: asn_ipfire.sh -a -f company.list 
            asn_ipfire.sh --network -f company.list 

Option --remove only affects entries made by asn_ipfire.sh itself.
  These entries are recognized by the 'Remark'-column in IPFire.
  To remove all entries done by this script, use 'ALL' as COMPANY 
  examples: asn_ipfire.sh -r "CompanyA, CompanyB" 
            asn_ipfire.sh -r ALL

1.1 Company Names:

Names needed to be separated by commas (,) (e.g. CampanyA,CompanyB,CompanyC,...)
If spaces are used for better readability, the string must be put into double quotes ("). (e.g. "CampanyA , CompanyB, CompanyC,...")
Any spaces, slashes and backslashes are skipped. (e.g. "Comp AnyA" is searching for "CompAnyA")
To find names with spaces in between, use the tilde (~) sign as substitution for space (e.g. "Comp~AnyA" is searching for "Comp AnyA")
Any matches which contain the given name as substring are found.
If the result shall be limited strictly to exact matches, the tilde (~) signs can be used as limiter (e.g. ~CompanyA~).
Asterisk (*) sign is allowed as wildcard, to find names with any characters in between of two name parts. (e.g. "Comp*AnyA")

1.2 Options

Most options should be self explaining. Though there are some additional descriptions below:

-c, --check
Check source files for availability
This option performs an pre-check of all activated sources. It reduces the risk of wrongly cleared network entries. In case that any external source cannot be reached, the script will stop without any changes to the ipfire. The script will not abort, if local sources are missing (defined as local_asn_file and local_net_file).
Note: Even with this option activated, mistakenly emptied entries can still happen, e.g. if a source is not reachable after the pre-check or if the source contain no data, etc.

-k, --keep
Keep temporary source files after finish
Option to keep temporary source files after the script ends. By default the source lists are downloaded to temperary files and automatically deleted when the script has finished. This removal can be disabled, to re-use an already downloaded source list on the next run of the script, and so prevent it from downloading again.
Note: To get an updated list from a source after using this option, the temporary file must be either deleted manually or the script must be run twice without this option.

--renumber
Renumber lines of customnetworks & customgroups files
By default the lines of IPFire files customnetworks & customgroups are renumbered automatically, when entries are added or removed by this script. Therefore this option should be obsolet. But in case the IPFire files are manipulated by hand (e.g. added or removed entries manually) then this option can be used to renumber the lines without any other changes to the entries.
Note: Normally the numbering is not visible to the IPFire user and a wrong numbering seems to have none effect.

--resort
Re-sort lines of customnetworks & customgroups files
By mixed use of this script and IPFire GUI Firewall Groups, the entries may become unsorted. This option re-sorts (order by name) and renumbers the IPFire files and entries again.

--backup
Backup customnetworks & customgroups before change
Option to create backups of both IPFire files (customnetworks.bak & customgroups.bak) before any changes to them are done.
This is helpfull if connection problems occures (source URL down, no internet connection, etc.) and therefore entries are not complete or even empty. See option --restore. Note: When running the script first time after a long period it is recommended to use this option once.

--restore
Restore last customnetworks & customgroups backup
This option restores backups of both IPFire files customnetworks.bak & customgroups.bak if existent. This is helpfull if connection problems occures (source URL down, no internet connecton, etc.) and therefore entries are not complete or even empty. See option --backup.

--rmbackup
Remove backup files customnetworks.bak & customgroups.bak
Remove existing backup files customnetworks.bak & customgroups.bak

-v, --verbose
Verbose mode
This option shows further information about script run status, the number of ASNs, the networks and IP's, which have been collected. This option is helpfull to compare results of different sources.

--raw
Create results with non-consolidated networks
This option skips the consolidating of unnecessary entries (due to overlapping or adjacents). It may help at result comparison of different sources.

-i, --interactive
Ask user before overwriting files
If this option is set, the user will be asked before a file will be overwritten and can abort the script. It is mainly intended for the IPFire mode. It will not ask when overwriting only temporary files.

--iprange
Use external tool iprange for consolidation
This option uses the external tool iprange for consolidating of unnecessary entries (due to overlapping or adjacents). This speeds up the script significantly when companies with many networks and IP's are targeted. This option requires the binary of iprange. For compiling iprange, see the instruction on the developers Wiki page. (Binaries iprange_amd64 and iprange_arm64 are provided alternatively). The path to the binary can be changed in the config file.

Examples:

Add new or update existing company networks to IPFire groups. Make a backup before the change:
asn_ipfire.sh --add "CompanyA,Company~NameB,~CompanyC~" --backup

In case there was no internet connection, above command will have deleted your entries for the given Companies. To restore to the state before.
asn_ipfire.sh --restore

Create a list of networks associated with companies starting with "G" and ending with "le". Enable detailed output.
asn_ipfire.sh --network "~G*le~" --verbose

Remove all entries from IPFire done by the script
asn_ipfire.sh -r "ALL"

1.3 Configuration File

With version 0.7.9 a optional configuration file was introduced. By default the file is names asn_script.conf. The name can be customized by editing the $configfile variable in the script header.
During execution of asn_ipfire.sh all lines from the configuration file will be sourced (included) in the script, right after the header part. That means, each variable of asn_ipfire.sh can be overwritten, if it is present in the config file.

1.4 Custom output format

A custom specific result file can be created with the option --custom , followed by the company names or a company file (-f).
By default this results in a simply list of networks. To costumize the output format, the variable outputline has to be defined. Set it in between of double quotes(")! This can be done either in the configuration file or the script header.
There a three special substitutions which can be used here: %network%, %company% and %number%, which counts the number of networks per company.

Note: The options --iptable and --afwall should not longer be used. They will be removed in future versions of the script. Use option --custom together with the following examples instead, which create the same output:

outputline="$iptables_path -A OUTPUT -d %network% -j REJECT"
outputline="$afwall_path -A \"afwall\" -d %network% -j REJECT"

Example of %company% and %number%:
outputline="$iptables_path -A OUTPUT -d %network% -j REJECT #%company% Nr.%number%"

Example for nftables:
outputline="nft add rule ip filter OUTPUT ip daddr %network% counter reject"

1.5 Exit codes

0 - OK
1 - arguments wrong or missing
2 - files write protected or missing
3 - user abort
4 - source error