============================================================================
Internet v5 commands
============================================================================

The !Internet application provides the services and protocols needed for
other TCP/IP applications to work. It also provides a variety of modules
and * Commands that duplicate UNIX commands. If you're a more experienced Internet user you may well find these useful; this section gives you more information about them.


The Internet module's * Commands
================================

The core of the !Internet application is a module named Internet. It is
stored as the !RunImage file within the application. It provides two
* Commands:

Command                 Use
-------                 ---
*InetGateway            May be used to enable or to disable IP layer packet
                        forwarding
*InetInfo               Displays Internet module internal statistics

Running the Internet application loads the Internet module; you can then use
the above * Commands.


The absolute programs
=====================

There are also a set of commands that are provided as Absolute files (ie
each file is a program that performs one command) in the bin subdirectory of
the Internet application. These are:

Command                 Use
-------                 ---
*ARP                    Address resolution display and control
*IfConfig               Configure network interface parameters
*Ping                   Send ICMP ECHO_REQUEST packets to network hosts
*Route                  Manually manipulate the routing tables

Although the above are actually programs, in the section that follows we've
treated them as * Commands because you're most likely to use them in just
the same way.


The Ethernet driver modules' * Commands
=======================================

The Ethernet driver modules (held in the drivers subdirectory of the
application) each provide a single * Command to give information.
The Ether3 module also provides a configuration command:

Command                 Use
-------                 ---
*Configure Ether3       Sets the configured state of Acorn Ethernet 3
                        cards
*<Device>Info           Displays driver module internal statistics

Running the Internet application loads any appropriate Ethernet driver
modules; you can then use any of the above * Commands that are relevant to
your interface(s).


Command syntax
==============

Special symbols are used when defining the syntax for commands:

* Angle brackets indicate that you must substitute an actual value. For
  example, <filename> means that you must supply an actual filename.

* Braces indicate that the item enclosed is optional. For example, [K] shows
  that you may omit the letter 'K'.

* A bar indicates an option. For example 0|1 means that you must supply the
  value 0 or 1.


* Commands
==========


*ARP
====

Address resolution display and control

Syntax
------
*ARP <host>
*ARP -a
*ARP -d <host>
*ARP -s <host> <phys_addr> [temp] [pub]
*ARP -f <filename>

Parameters
----------
<host>          an Internet host specified either by name (which must be
                present in the host name data base <InetDBase$Path>hosts) or
                by address (using the standard Internet dot notation)

<phys_addr>     the physical address of <host> given in Ethernet format (ie
                six hexadecimal bytes separated by colons)

<filename>      the full pathname of a file containing multiple entries to
                be set in the ARP table

Use
---
The ARP program displays and modifies the Internet-to-Physical-address
translation tables located in the Internet module and used by the address
resolution protocol ARP.

With no flags, the program displays the current ARP entry for <host>.

The -a flag makes the program display all the ARP entries currently in its
table.

The -d flag makes the program delete an entry for <host>.

The -s flag makes the program create an ARP entry for the host called <host>
with the physical address <phys_addr>.

* The entry will be permanent unless the word temp is given in the command.

* The entry will be `published' if the word pub is given. This system will
  then act as an ARP or Reverse ARP server, responding to requests for
  <host>'s physical address even though the host address is not its own.

The -f flag causes the file <filename> to be read and multiple entries to be
set in the ARP tables. Entries in the file should be of the form:

<host> <phys_addr> [temp] [pub]

with argument meanings as given above.

If you don't know the physical address of an interface, you can use the
*InetInfo command to find it.

Examples
--------
*ARP tp1
*ARP -a
*ARP -d 01.01.01.01
*ARP -s tp1 01.01.01.01.01.01 temp
*ARP -f adfs::HardDisc.$.Internet.ARP_Table

Related commands
----------------
None


*Configure Ether3
=================

Sets the configured state of Acorn Ethernet 3 cards

Syntax
------
*Configure Ether3 <options> [<card>]

Parameters
----------
<options>       version dependent parameters: 'Default' sets a sensible
                state

<card>          the expansion card's number, as given by *Podules

Use
---
*Configure Ether3 sets the configured state of all fitted Acorn Ethernet 3
cards, or of a single <card> specified by its expansion card slot number.

*Configure Ether3 Default sets the configured state to a sensible default.

Example
-------
*Configure Ether3 Default 0

Related commands
----------------

*Status Ether3


*<Device>Info
=============

Displays driver module internal statistics

Syntax
------
*EBInfo

Use
---
A *<Device>Info command displays detailed information about driver module
activity. Note that this command is supplied by the driver that comes with a
network interface, rather than by RISC OS. Each of the standard Acorn
drivers provides such a command. We expect third party drivers to provide a
corresponding command; you should see the documentation supplied for the
command name.

It is presented mainly as an aid to trouble-shooting, should you require it.

Example
-------

*EBInfo
EtherB interface statistics

eb0: 80C04 Network slot, enabled, hardware address 00:00:A4:10:17:00

packets received = 27735              packets transmitted = 2391
bytes received = 2040394              bytes transmitted = 392460
receive interrupts = 27279            transmit interrupts = 2390

Standard clients:

Frame = &0800, ErrLvl=00, AddrLvl=01, FrmLvl=00
Frame = &0806, ErrLvl=00, AddrLvl=01, FrmLvl=00
Frame = &0835, ErrLvl=00, AddrLvl=01, FrmLvl=00

Log:EtherB messages can appear here

Related commands
----------------
*InetInfo


*IfConfig
=========

Configure network interface parameters

Syntax
------

*IfConfig [-e] interface [inet <host> [<parameters>]]


Parameters
----------

<interface>     the two character name (as defined by the manufacturer)
                and unit number (starting from 0 for the first of that
                type fitted) of an interface - eg en0 (Acorn Ethernet 2
                unit 0), ea1 (Acorn Ethernet 3 unit 1), ec0 (Econet)

<host>          an Internet host specified either by name (which must be
                present in the host name data base <InetDBase$Path>hosts)
                or by address (using the standard Internet dot notation)

Use
---

The IfConfig program is used to assign an Internet address to a network
interface supported by the Internet module, and/or to configure network
interface parameters. It must be used at Internet module startup time to
define the network address of each interface present on a machine; it may
also be used at a later time to redefine an interface's address or other
operating parameters.

You can set the following parameters with the IfConfig program:

up              Mark an interface 'up'. This may be used to enable an
                interface after going *IfConfig - down. It happens
                automatically when setting the first address on an
                interface. If the interface was reset when previously marked
                down, the hardware will be re-initialised.

down            Mark an interface 'down'. When an interface is marked
                'down', the system will not attempt to transmit messages
                through that interface. If possible, the interface will be
                reset to disable reception as well. This action does not
                automatically disable routes using the interface.

arp             Enable the use of the Address Resolution Protocol in mapping
                between network level addresses and link level addresses
                (default), for mapping between Internet addresses and
                Ethernet addresses.

-arp            Disable the use of the Address Resolution Protocol.

metric <n>      Set the routing metric of the interface to n (default 0).
                The routing metric is used by the routing protocol. Higher
                metrics have the effect of making a route less favourable;
                metrics are counted as additional hops to the destination
                network or host.

netmask <mask>  Specify how much of the address to reserve for subdividing
                networks into sub-networks. The mask includes the network
                part of the local address and the subnet part, which is
                taken from the host field of the address. The mask can be
                specified as a single hexadecimal number with a leading 0x,
                as an Internet address using the standard dot notation, or
                as a pseudo-network name listed in the network table
                <Inet$DBase>networks. The mask contains 1's for the bit
                positions in the 32-bit address which are to be used for the
                network and subnet parts, and 0's for the host part. The
                mask should contain at least the standard network portion,
                and the subnet field should be contiguous with the network
                portion.

broadcast       Specify the address to use to represent broadcasts to the
                network. The default broadcast address is the address with a
                host part of all 1's.

If you don't use any of the optional parameters, the IfConfig program
displays the current configuration for a network interface.

The -e option makes IfConfig place any fatal error report string in the
system variable Inet$Error instead of writing it to the standard output.

Example
-------
*IfConfig -e ea0 inet tp1 up

Related commands
----------------
None


*InetGateway
============

May be used to enable or to disable IP layer packet forwarding

Syntax
------

*InetGateway On|Off

Parameters
----------
On              enable IP layer packet forwarding

Off             disable IP layer packet forwarding

Use
---
*InetGateway may be used to enable or to disable IP layer packet forwarding
(ie gateway operation) if multiple network interfaces are present.

The default state is off.

Example
-------
*InetGateway On

Related commands
----------------
None


*InetInfo
=========

Displays Internet module internal statistics

Syntax
------
*InetInfo [r] [i] [p]

Parameters
----------
r               give details of internal resource usage (the default)

i               give details of interfaces fitted

p               give details of protocols

Use
---
*InetInfo displays information and statistics about the current state of the
Internet module, which forms a part of the AUN software. Most of the
information displayed is runic in nature. It is presented mainly as an aid
to trouble-shooting, should you require it.

Example
-------
*InetInfo r

Resource usage:

Sockets
    Active 10

Packet forwarding not in operation

Related commands
----------------
None


*Ping
=====

Send ICMP ECHO_REQUEST packets to network hosts

Syntax
------
*Ping [-r] [-v] [<-s packetsize>] [<-c count>] <host>

Parameters
----------

<host>          an Internet host specified either by name (which must be
                present in the host name data base <InetDBase$Path>hosts)
                or by address (using the standard Internet dot notation)

<-s> <packetsize>    the size of packet to send (default is 64 bytes)

<-c> <count>         the number of packets to send (default is 1)


Use
---
An Internet can be a large and complex aggregation of network hardware,
connected together by gateways. Tracking a single-point hardware or software
failure can be difficult. The Ping program utilises the ICMP protocol's
mandatory ECHO_REQUEST datagram to elicit an ICMP ECHO_RESPONSE from a host
or gateway. ECHO_REQUEST datagrams (or pings) have an IP and ICMP header,
and then an arbitrary number of padding bytes used to fill out the packet.

The optional -r parameter makes the Ping program bypass the normal routing
tables and send directly to a host on an attached network. (If the host is
not on a directly attached network an error is returned.) You can use this
option to 'ping' a local host through an interface that has no route through
it.

The optional -v parameter causes verbose output: any ICMP packets other than
ECHO RESPONSE that are received are listed.

When using Ping for fault isolation you should first run it on your local
host, to verify that your local network interface is up and running. Then
you should 'ping' hosts and gateways that are further and further away.

If you don't give a <count> the Ping program now repeats indefinitely
sending datagram pers second and expects an ECHO_RESPONSE to be returned.
If you give a <count> Ping sends one datagram per second up to that number,
and prints one line of output for every ECHO_RESPONSE returned.
No output is produced if there is no response.

Packet loss statistics are computed and a brief summary is displayed when
all responses have been received, or when the program times out, or when you
terminate the program.

RISC OS Ping messages are not time-stamped.

Example
-------
*Ping -v -s 1024 -c 20  tp1

Related commands
----------------
None


*Route
======

Manually manipulate the routing tables

Syntax
------
*Route [-e] [-f] add [-net|-host] <destination> <gateway>
*Route [-e] [-f] delete [-net|-host] <destination> <gateway>

Parameters
----------
<destination>   an Internet host or network specified either by name
                (which must be present in the respective host or network
                name data base <InetDBase$Path>-) or by address (using the
                standard Internet dot notation)

<gateway>       the next-hop gateway to which packets should be addressed

<metric>        a count giving the number of hops to the destination

Use
---
You can use the Route program to manually manipulate the Internet
module's network routing tables.

The <metric> must be zero if the destination is on a directly-attached
network, and non-zero if the route utilises one or more gateways. If you're
adding a route with <metric> 0, the <gateway> given is the address of this host
on the common network, indicating the interface to be used for transmission.

Routes to a particular host are distinguished from those to a network by
interpreting the Internet address associated with <destination>. The optional
keywords net and host force the <destination> to be interpreted as a network
or a host, respectively. Otherwise, if the <destination> has a local address
part of 0 or if it's the symbolic name of a network, then the route's
presumed to be to a network; else the route's presumed to be to a host. All
symbolic names specified for a destination or gateway are looked up first as
a host name; if this fails, the name is then looked up as a network name.

The -e option makes Route place any fatal error report string in the system
variable Inet$Error instead of writing it to the standard output.

The -f option makes Route delete all gateway entries in the Internet
module's routing tables. If this is used in conjunction with an add command,
the tables are flushed first.

Examples
--------
*Route -f add net 1 0.0.0.1 1
*Route -e delete host tp1 tp4

Related commands
----------------
None


*Status Ether3
==============

Displays the configured state of Acorn Ethernet 3 cards

Syntax
------

*Status Ether3

Use
---
*Status Ether3 displays the configured state of all fitted Acorn Ethernet 3
cards.

Example
-------
*Status Ether3
ether3 enabled 0
ether3 newinet 0

Related commands
----------------
*Configure Ether3


*InetStat
=========
Routing information is now displayed using *InetStat -r instead
of *Route -a in Internet 4.
          
Protocol statistics are now displayed using *InetStat -s instead of
*InetInfo p in Internet 4.


*InetCheckSum
=============
The *InetChecksum command has been withdrawn. IP and TCP checksums
are now always sent and checked. UDP checksums are always checked
if present. UDP checksums are not included by default, but you
can use 

      *Sysctl -w net.inet.udp.checksum=1
      
to turn them on.  This was done to conform more closely to the
Internet standards, and in view of the fact that the checksumming
routine is 8 times faster than previous Internet modules.


