Swroptions(1)

NAME
swroptions - SWR options file provides a mechanism for passing options to Cisco's IOS-Linux based software router.

DESCRIPTION
The SWROPTIONS File can be used to supply values for options to the SoftWare Router (SWR). This provides an ease-of-use feature which makes the command line not quite so complicated. The SWROPTIONS file is optional. The SWR looks for it by default in $HOME/SWROPTIONS. You can override the default location using the "-o <path>" option via command line.

SWROPTIONS FILE
Syntax of the SWR options file.

# Comment

# UNLABLED SECTION:

option-key=option-value

...

# LABLED SECTION:

[section-name]

# PROPERTY DEFINITION:

option-key=option-value

[section-name]

# PROPERTY DEFINITION:

option-key=option-value

...

UNLABELED SECTION
UNLABELED SECTION occurs at the beginning of the file.

soft-rommon
    - Path of the SWR image(i.e., this option is applicable only for swr_reload utility).

launchapp
    - SWR image to be launched (i.e., this option is applicable only for swr_reload utility).

ethernet-slots
    - The value for this option is an integer which specifies the number of Ethernet interface slots(each slot consists of 4 ports). The default value is 2.

debug
    - The value for this option is a boolean value. It can be specified as either "true", "t", "1" for TRUE, or "false", "f", or "0" for FALSE. The value is case-insensitive. It governs the output of certain debug information (and is not controlled nor associated with any IOS commands). The default value is FALSE.

ram - The value for this option is an integer which specifies how much router memory is in use, in Mbytes. The default value is 512.

local-console-disable
    - The value for this option is a boolean value. It can be specified as either "true", "t", "1" for TRUE, or "false", "f", or "0" for FALSE. The value is case-insensitive. It governs whether the router console output is directed to its process standard output (TRUE), or to the virtual console (FALSE). Refer to swrvcon(1) for more information on the virtual console. The default value is TRUE.

node-lock-type
    - The value for this option is either machine or storage. If node-lock-type is specified as "storage" then user can exchange HDD or CF from one machine to another and same license key could be re-used on new machine. Users can not re-use the same license key on different machines when this keyword is set to "machine". But can use in differnt filesystems on same machine. The Default is machine.

linux-vlan-stripped-from-pak
    - The Linux Kernel behavior of handling dot1q tagged packets changed after RHEL bug 1135347. Post this kernel fix, the Linux applications should also change their packet reception method. c5921 software automatically checks for specific Linux kernel versions and adapts to this new method for centos Linux distributions(except kernel ver. 2.6.36). For other flavors like Debian, Ubuntu, Fedora, etc., the new option "linux-vlan-stripped-from-pak" should be added in SWROPTIONS to indicate to c5921 software if the kernel fix is available or not. This variable has to be set to true for kernel versions that has the patch(for the new IOS fix to be effective) and to false for kernel versions that does not have the patch(for the old IOS method to be effective)

LABELED SECTION
Each labeled section is introduced by the syntactic form "[section-name]", where "section-name" is a word naming or labeling the section. It consist the two labels [filemap] and [interface].

FILEMAP SECTION
File mapping establishes a mapping between a given IOS File System name and a given Linux directory. SWROPTIONS file can have zero or more file mapping. Each such file mapping is in a section of the SWR OPTIONS file delimited by a line containing "[filemap]". Once you start a Filemap section, you may specify a series of keyword=value lines describing a specific file mapping. Each keyword=value line pertains to a single mapping, up until the next [filemap] delimiter line, or until the end of the file. The keyword=value lines describing a file mapping can be any of the following:

ios=<IOS_File_System_Name>
    The "ios" keyword provides the IOS File System name. The value provided to the right of the equals sign must be the IOS File System name. For example, "flash", "flash0", "flash1", "unix", as well as other names, may be used. The IOS File System Name must conform to IOS File System naming conventions. Usually, IOS File System Names end in a colon (":"); however, for this option, you omit the colon. This sub-option is required.

linux=<Linux_Directory_Name>
    The "linux" keyword provides a Linux directory to which the IOS file system will be mapped. The directory need not exist at the time the mapping is made; for example, it could name a mountable file system which is not presently mounted. The value supplied must conform to Linux path naming conventions, and it must ultimately name a directory. This sub-option is required.

access=<rw_or_ro>
    This sub-option establishes an access policy for access to the filesystem from IOS. This is in addition to any access policies defined in Linux. The two possible sub-values are "rw", for read and write access; and "ro", for read-only access. This sub-option is optional. The default is "rw".

INTERFACE SECTION
Interface mapping is in a section of the SWR OPTIONS file delimited by line containing "[interface]". Once you start an interface section, you may specify a series of keyword=value lines describing a specific interface mapping. Each keyword=value line pertains to a single mapping, up until the next "[interface]" delimiter line, or until the end of the file. The keyword=value lines describing an interface mapping can be any of the following:

type=<raw|tap>
    Two packet capture types are supported: "raw" and "tap". This sub-option must be specified.

linux=<linux-network-interface-name>
    The Linux name of the associated interface. For type "raw", this will be the name of an associated physical ethernet interface, such as "eth0", "eth1", etc. For type "tap", this will be the Linux name of the Tap interface, such as "tap0", "tap1", etc. This sub-option must be specified.

ios=<ios-network-interface-name>
    The IOS name of the associated interface. This will always be of the form "e<n>/<m>", where <n> is a "bay" or "slot" number and <m> is a port number within the bay. There are always 4 ports within each bay or slot. This sub-option must be specified. Note that for interface-mappings, the "linux" and "ios" suboptions must specify unique values amongst the set of interface-mappings.

promiscuous(or)prom=<t/f>
    Promiscuous mode. If the sub-value is "t", "T" or "1", then the associated Linux interface will be placed in promiscuous mode. If the sub-value is "f", "F", or "0", then the Linux interface will not be placed in promiscuous mode. For "raw" interface, if promiscuous mode is TRUE it will process multicast packets, if promiscuous is set to FALSE it will drop multicast packets. For "tap" interfaces, the "promiscuous" mode is ignored. The default value for this sub-option is "t", meaning promiscuous mode is enabled.

monitor-state=<boolean>
    Enable/disable monitoring for the Linux physical interface. Default value is true.

push-mon-int=<t/f>
    If push-mon-int value is "true", "T", "t" or "1", then speed and duplex cli will be available in IOS side, and if the value is "false", "f" ,"F" or "0" , then speed and duplex cli will not be available in ios side. The default value is false. The speed/duplex cli configured in ios side will get updated to linux side , only when both push-mon-int and monitor-state values are true. If push-mon-int is configured on a "tap" interface, it would be ignored.

EXAMPLES
Example of SWROPTIONS file.
 #COMMENTS
 soft-rommon=./
 launchapp=c5921i86-universalk9-ms.SPA
 ethernet-slots=2
 debug=t
 node-lock-type=machine
 linux-vlan-stripped-from-pak=true
 [filemap]
 ios=flash
 linux=/mnt/sdb1
 [interface]
 linux=eth0
 ios=eth0/0
 type=raw
 prom=true
 monitor-state=true
 push-mon-int=true
 [interface]
 linux=tap0
 ios=eth1/0
 type=tap
 monitor-state=true

COMMAND-LINE OPTIONS
User can specify the required options using command line also. These options overrides options specified in the SWROPTIONS file. The following are the command line options.

-d  Generate debug information outside of IOS operation. Should only be used under guidance of Cisco support personnel.

-e  Number of four port ethernet line cards to emulate. The default is 2, resulting in eight ethernet interfaces in the Software Router.

-h  Display command help.

-L  Disable the local IOS console. Requires the use of swrvcon to access the IOS console. This mode should be used what starting the Software Router from a Linux initialization script.

-m memory_size
    Software Router memory size in megabytes. The default is 512.

-n machine/storage
    This option specifies the node-lock-type value either machine or storage. If option is specified as "storage" then user can exchange HDD or CF from one machine to another and same license key could be re-used on new machine. Users can not re-use the same license key on different machines when this option is specified as "machine". But can use in differnt filesystems on same machine. The Default is machine.

-v  This option causes the application to output its current version and then terminate.

-i Interface-mapping
    This option specifies a mapping between a Linux network interface name and a corresponding IOS interface. This option establishes such an association and arranges for internal packet capture from the associated Linux network interface to appear as incoming packets on the associated IOS interface. In addition, it arranges that outgoing packets on the IOS interface to be injected for output on the Linux interface. See "Interface-mapping Command Line Options" below for more information.

-f File-mapping
    This option specifies a mapping of an IOS file system into a corresponding Linux directory. Once this mapping is made, access to the Linux directory can be performed from within IOS. See "File-mapping Command Line Options" below for more information.

-o path
    This option specifies the path in the Linux file system to a SWROPTIONS file. The default for the location of this file is $HOME/SWROPTIONS. This file may or may not exist. If it doesn't exist, then values for options are obtained strictly from the command line. If it does exist, either at the default location or at the location specified using "-o <path>", then options specified in the SWROPTIONS file can be overridden by options specified in the command line. The format of the SWROPTIONS file is explained below.

INTERFACE-MAPPING Command Line Options
The "-i <interface-mapping> command line option establishes a mapping between a given Linux network interface and a given IOS network interface. The "interface-mapping" consists of a series of sub-options, with each sub-option separated by a colon (':'). Each sub-option consists of a sub-keyword and sub-value, separated by equals ('='). The allowed sub-keywords consist of the following:

type=<raw|tap>
    Two packet capture types are supported: "raw" and "tap". "Raw" interface mapping means that packets are captured and injected directly at the Linux Ethernet driver. This is the preferred mode for general packet capture and injection. "Tap" interface mapping implies the use of a "tap" interface, a kind of virtual network interface that can be attached at one end to various Linux facilities. For example, a "tap" interface can be used as the endpoint for various co-resident applications to communicate with and through the Software Router. It can also be assigned to a bridge group along with a Linux physical network interface to provide packet capture and injection. This sub-option is required.

linux=<linux-network-interface-name>
    The Linux name of the associated interface. For type "raw", this will be the name of an associated physical ethernet interface, such as "eth0", "eth1", etc. For type "tap", this will be the Linux name of the Tap interface, such as "tap0", "tap1", etc. This sub-option is required.

ios=<ios-network-interface-name>
    The IOS name of the associated interface. This will always be of the form "e<n>/<m>", where <n> is a "bay" or "slot" number and <m> is a port number within the bay. There are always 4 ports within each bay or slot. The number of bays/slots is determined by the "-e" command line option. This sub-option is required.

promiscuous(or)prom=<t/f>
    Promiscuous mode. If the sub-value is "t", "T" or "1", then the associated Linux interface will be placed in promiscuous mode. If the sub-value is "f", "F", or "0", then the Linux interface will not be placed in promiscuous mode. For "raw" interface, if promiscuous mode is TRUE it will process multicast packets, if promiscuous is set to FALSE it will drop multicast packets. For "tap" interfaces, the "promiscuous" mode is ignored. The default value for this sub-option is "t", meaning promiscuous mode is enabled.

monitor-state=<boolean>
    Enable/disable monitoring for the Linux physical interface. Default value is true.

push-mon-int=<t/f>
    If push-mon-int value is "true", "T", "t" or "1", then speed and duplex cli will be available in IOS side, and if the value is "false", "f" ,"F" or "0" , then speed and duplex cli will not be available in ios side. The default value is false. The speed/duplex cli configured in ios side will get updated to linux side , only when both push-mon-int and monitor-state values are true. If push-mon-int is configured on a "tap" interface, it would be ignored.

Example:
    c5921i86-universalk9-ms.SPA -i 'type=raw:linux=eth0:ios=e0/0:prom=t:push-mon-int=t' It is recommended that the entire value portion of the "-i" option be enclosed in single quotes, in order to avoid unanticipated interpretation by the Linux shell. Note that for interface-mappings, the "linux" and "ios" suboptions must specify unique values amongst the set of interface-mappings.

FILE-MAPPING Command Line Options
The "-f <file-mapping> command line option establishes a mapping between a given IOS File System name and a given Linux directory. The "file-mapping" consists of a series of sub-options, with each sub-option separated by a colon (':'). Each sub-option consists of a sub-keyword and sub-value, separated by equals ('='). The allowed sub-keywords consist of the following:

ios=<IOS_File_System_Name>
    The "ios" keyword provides the IOS File System name. The value provided to the right of the equals sign must be the IOS File System name. For example, "flash", "flash0", "flash1", "unix", as well as other names, may be used. The IOS File System Name must conform to IOS File System naming conventions. Usually, IOS File System Names end in a colon (":"); however, for this command line option, you omit the colon. This sub-option is required.

linux=<Linux_Directory_Name>
    The sub-value supplied for the "linux" sub-keyword provides a Linux directory to which the IOS file system will be mapped. The directory need not exist at the time the mapping is made; for example, it could name a mountable file system which is not presently mounted. The value supplied must conform to Linux path naming conventions, and it must ultimately name a directory. This sub-option is required.

access=<rw_or_ro>
    This sub-option establishes an access policy for access to the filesystem from IOS. This is in addition to any access policies defined in Linux. The two possible sub-values are "rw", for read and write access; and "ro", for read-only access. This sub-option is optional. The default is "rw".

Example:
    c5921i86-universalk9-ms.SPA -f 'ios=flash0:linux=/tmp:access=rw' Thereafter, any IOS accesses to file system "flash0:" will result in a view into the Linux "/tmp" directory. Any number of mappings may be specified in separate -f options. It is recommended that the entire value portion of the "-f" option be enclosed in single quotes, in order to avoid unanticipated interpretation by the Linux shell. Note that for file-mappings, the "ios" suboption value must be unique amongst the full set of file-mappings. Note that by default, the "unix:" IOS file system name is mapped to the current working directory of the process running the application. This can be overridden in a command line file mapping, so that IOS file system "unix:" is mapped to a different Linux directory. However, beware of this, because the application might not run properly because of licensing restrictions. It is recommended that if you are going to re-map the "unix:" IOS file system, you do so before licensing is installed, and that you keep this mapping thereafter.

EXAMPLES

=> ./c5921i86-universalk9-ms.SSA -e 2 -L -i 'linux=eth1:ios=e0/0:type=raw' -i 'linux=eth2:ios=e0/1:promiscuous=true:
    type=raw:push-mon-int=true:monitor-state=true' 100 -n storage &"

=> ./c5921i86-universalk9-ms.SSA -e 1 -L -i 'linux=eth0:ios=e0/0:prom=false:type=raw' -f 'linux=/opt/cisco/c5921:ios=flash0' 100 -n storage &

=> ./c5921i86-universalk9-ms.SSA -e 1 -L -i 'linux=tap0:ios=e0/0:type=tap' -f 'linux=/opt/cisco/c5921:ios=flash0' 100  -n machine &

SEE ALSO
swr-application(1)

COPYRIGHT
Copyright (c) 2013 by Cisco systems, Inc.