Home Page The Club Computers News Links Glossary EYAWTK
Before Amiga Background ICS OCS ECS AGA ??? PPC
U-Boot SLB Linux Amiga OS Dual Boot Motherboards Peripherals Other
Initialisation Installation OS4 Updates About OS4 File Systems Networking Printing Other
Introduction File System Workbench Preferences Commands Error Msgs Miscellaneous

AmigaOS 4.0 - About OS4 - Commands

ADDNETINTERFACE Networking
Purpose: To initialise network interfaces defined to the system.
Format: ADDNETINTERFACE {<interface>} [QUIET] [TIMEOUT <n>]
Template: INTERFACE/M, QUIET/S, TIMEOUT/K/N
Path: C:ADDNETINTERFACE
ADDNETINTERFACE is used by the S:Startup-Sequence to initialise your defined network connections, which are normally stored in DEVS:NetInterfaces, although this is not the default.

One or more network connections can be specified using the <interface> argument, but it is more common to simply point it at the DEVS:NetInterfaces directory and exclude any icon (.info) files.

The QUIET option is used to suppress any error messages (the default is to print them).

The TIMEOUT option can be used to specify how long the program should wait for DHCP configuration to conclude (default is a timeout of 60 seconds).

Network Definitions
As stated above, Network Definitions are normally stored in DEVS:NetInterfaces, and contain various parameters used to configure your network connections. Each line of the file must correspond to an option; if a line is introduced by a '#' or ';' character it will be ignored (so are empty lines). The following options are supported:

DEVICE=<device> Must be provided; the name of the SANA-II device driver. This should be the complete, fully qualified path to the driver, suitable for passing to 'OpenDevice()'. If no complete path is provided, the library will look into 'Devs:Networks'. Thus, "DEVS:Networks/ariadne.device" is equivalent to "ariadne.device".
UNIT=<unit> Unit number of the device driver to open. The default is to use unit 0.
IPTYPE=<iptype> You can use this parameter to override the packet type the stack uses when sending IP packets; default is 2048 (for Ethernet hardware).
ARPTYPE=<arptype> You can use this parameter to override the packet type the stack uses when sending ARP packets. Default is 2054; this parameter only works with Ethernet hardware and should not be changed.
IPREQUESTS=<ipreqs> The number of IP read requests to allocate and queue for the SANA-II device driver to use. The default value is 32, larger values can improve performance, especially with fast device drivers.
WRITEREQUESTS=<writereqs> The number of IP write requests to allocate and queue for the SANA-II device driver to use. The default value is 32, larger values can improve performance, especially with fast device drivers.
ARPREQUESTS=<arpreqs> The number of ARP read requests to allocate and queue for the SANA-II device driver to use. The default value is 4.
DEBUG=YES | NO You can enable debug output for this interface (don't worry, you can always disable it later) to help in tracking down configuration problems. At this time of writing, the debug mode will, if enabled, produce information on the progress of the DHCP configuration process.
POINTTOPOINT/K=YES | NO This indicates that the device is used for point to point connections. The stack automatically figures out whether the SANA-II device driver is of the point to point type, so you should not need to specify this option.
MULTICAST=YES | NO This tells the stack that this device can handle multicast packets. 'YES' only works with Ethernet hardware (where it's enabled by default anyway).
DOWNGOESOFFLINE=YES | NO This option is useful with point to point devices, like 'ppp.device'. When specified, bringing the interface 'down' (via the 'ConfigureNetInterface' program) or shutting down the stack will cause the associated SANA-II device driver to be switched offline (via the 'S2_OFFLINE' command).
REPORTOFFLINE=YES | NO When a device is switched offline, you may want to know about it. This is helpful with SLIP/PPP connections which run over a serial link which accumulates costs while it is open. When the connection is broken and the device goes offline, you will receive a brief notification of what happened. However, if you tell the library itself to shut down, no notification that a device was switched offline will be shown.
REQUIRESINITDELAY=YES | NO Some devices need a little time to settle after they have been opened or they will hickup and lose data after the first packet has been sent. The original 'Ariadne I' card is one such device. For these devices, the 'YES' option will cause a delay of about a second before the first packet is sent. This option defaults to 'YES'.
COPYMODE=SLOW | FAST This option is for chasing subtle bugs in the driver interface with cards like the original 'Ariadne I'. Cards like these do not support writing to the hardware transmit buffer in units other than 16 bits a piece. Default is 'SLOW', which is compatible with the Ariadne I. But if you're feeling adventurous, try the 'FAST' option (and don't complain if it doesn't work for you!).
FILTER=OFF | LOCAL | IPANDARP | EVERYTHING This option enables the use of the Berkeley packet filter for this particular interface. Possible choices for the key are:
OFF - Disables the filter.
LOCAL - Enables filtering on all IP and ARP packets that are intended for this particular interface. Packets intended for other interfaces or hosts are ignored.
IPANDARP - Enables filtering on all IP and ARP packets that happen to fly by this interface, no matter whether the packets are intended for it or not. This requires that the underlying network device driver is opened for exclusive access in so-called 'promiscuous' mode. This may not work if other clients (Envoy, ACS) need to keep the driver opened.
EVERYTHING - Identical to IPANDARP, but will also filter all other kinds of packets that may show up.
Default for this option is 'LOCAL'. Note that by using this option you merely define what the filter mechanism can do and what it cannot do. The filter is not enabled when you add the interface.
HARDWAREADDRESS=<address> You can specify the hardware address (layer 2 address, MAC address) this interface should respond to when it is first added and configured. This usually works only once for each interface, which means that once an address has been chosen you have to stick with it until the system is rebooted. And it also means that the first program to configure the address will manage to make its choice stick. The hardware address must be given as six bytes in hexadecimal notation, separated by colon characters, like this:
    HARDWAREADDRESS=00:60:30:00:11:22
Take care, there are rules that apply to the choice of the hardware address, which means that you cannot simply pick a convenient number and get away with it. It is assumed that you will want to configure an IEEE 802.3 MAC address, which works for Ethernet hardware and is six bytes (48 bits) in size.

The name of the configuration file defines the name of the respective interface. Interface names must be unique, and the case of the names does not matter. For historic reasons interface names cannot be longer than 15 characters (and you thought that the MS-DOS 8.3 naming scheme was bad). Beyond this no restrictions on naming conventions apply.

Running from Workbench
The AddNetInterface program can be invoked from Workbench, too. It operates on the same configuration files with the same keywords, etc. To make it work, create an icon for your interface configuration file (it must be a project icon) and put 'AddNetInterface' into its default tool. Make sure that the project has enough stack space assigned (4000 bytes minimum), then double-click on the icon. If things should go wrong, you will see an error requester pop up, and no further initialization will be done. You can configure two options in the project file's tool types: QUIET and TIMEOUT. These are identical to the two parameters of the same name you could pass on the command line; they define whether the program should print any error messages (the default is to print them) and how long the program should wait for DHCP configuration to conclude (default is a timeout of 60 seconds).

In addition to the purely static interface configuration information you can also tell the configuration program to do something about the interfaces once they have all been added. That's when the following configuration file parameters will be taken into account:
ADDRESS=<address> This configures the IP address of the interface. The parameter you supply should be an IP address in dotted-decimal notation ("192.168.0.1"). Don't pick a symbolic host name as the system may not yet be in a position to talk to name resolution server and translate the symbolic name. In place of the IP address you can also specify "DHCP" (Dynamic Host Configuration Protocol). As the name suggests, this will start a configuration process involving the DHCP protocol which should eventually yield the right IP address for this host. Note that this configuration procedure only works for Ethernet hardware.
ALIAS=<address> In addition to the primary interface address you can assign several aliases to it. These must be specified in dotted-decimal notation ("192.168.0.1"). Alias addresses are added after the primary interface address has been configured.
STATE=UP | DOWN By default, interfaces whose addresses are configured will switch automatically to 'up' state, making it possible for the TCP/IP stack to use them for network I/O. You can override this by using the 'STATE=DOWN' switch.
NETMASK=<netmask> This selects the subnet mask for the interface, which must be specified in dotted-decimal notation ("192.0.168.1"). In place of the subnet mask you can also specify "DHCP" (Dynamic Host Configuration Protocol). As the name suggests, this will start a configuration process involving the DHCP protocol which should eventually yield the right subnet mask for this host. Note that this configuration procedure only works for Ethernet hardware.
DESTINATION=<destaddr>
DESTINATIONADDR=<destaddr>
The address of the point-to-point partner for this interface; must be specified in dotted-decimal notation ("192.168.0.1"). Only works for point-to-point connections, such as PPP.
METRIC=<route> This configures the interface route metric value. Default is 0.
MTU=<mtu> You can limit the maximum transmission size used by the TCP/IP stack to push data through the interface. The interface driver will have its own ideas about the maximum transmission size. You can therefore only suggest a smaller value than the driver's preferred hardware MTU size.
CONFIGURE=DHCP You can use DHCP configuration for this interface and protocol stack internals, namely the list of routers (and the default gateway) to use and the domain name servers. This option allows you to bring up the complete network configuration in one single step. You can request that a particular IP address is assigned to this interface by the DHCP process by specifying CONFIGURE=DHCP and your choice of ADDRESS=xxx.xxx.xxx.xxx.
LEASE=<lease> This is a complex option which can be used to request how long an IP address should be bound to an interface. Several combinations of options are possible. Here is a short list: LEASE=300 or LEASE=300seconds - These request a lease of exactly 300 seconds, or five minutes.
LEASE=30min - This requests a lease of 30 minutes.
LEASE=2hours - This requests a lease of 2 hours.
LEASE=1day - This requests a lease of 1 day.
LEASE=4weeks - This requests a lease of 4 weeks. LEASE=infinite - This requests that the IP address should be permanently bound. Blank spaces between the numbers and the qualifiers are supported. The qualifiers are tested using substring matching, which means for example that "30 minutes" is the same as "30 min" and "30 m". Note that the requested lease time may be ignored by the DHCP server. After all, it is just a suggestion and not an order.
ID=<name> This option works along with the CONFIGURE=DHCP process. It can be used to tell the DHCP server by which name the local host should be referred to. Some DHCP servers are on good terms with their local name resolution services and will add the name and the associated IP address to the local host database. The name you can supply here cannot be longer than 255 characters and must be at least 2 characters long. Keep it brief: not all DHCP servers have room for the whole 255 characters.

Example 1:

3.OS4:> ADDNETINTERFACE DEVS:NetInterfaces/ETH3COM initialises just the ETH3COM network definition which might look something like: # DEV:NetInterfaces/ETH3COM
# File generated by Dialer 50.14 (18.9.2004)
# On Thursday, 22-Sep-05 at 09:33:12
device=eth3com.device
hardwaretype=Ethernet
configure=dhcp

Example 2:

3.OS4:> ADDNETINTERFACE DEVS:NetInterfaces/~(#?.info) QUIET attempts to initialise any of the network definitions, excluding .info files.


Return to Commands Selection

Disclaimer: Amiga Auckland have prepared the above information for the use of its members based on our experiences and as such is subject to revision at any time. Amiga Auckland cannot guarantee any of the information and cannot be held accountable for any issues that may result from using it.


Copyright 2006 Amiga Auckland Inc. All rights reserved.
Revised: February 9, 2006.