filcon(1)

NAME
filcon - the RPC2 filter control utility.

SYNOPSIS
filcon filcon isolate -s srv1 [srv2 ... ] -c clnt1 [clnt2 ....] filcon join -s srv1 [srv2 ... ] -c clnt1 [clnt2 ....] filcon clear -s srv1 [srv2 ... ] -c clnt1 [clnt2 ....] filcon partition -s srv1 -c clnt1 filcon heal -h hostname1 port1 -h hostname2 port2 filcon oldpartition -h hostname1 port1 -h hostname2 port2 filcon slow -h hostname1 port1 -h hostname2 port2 filcon help

DESCRIPTION
filcon mainpulates the failure filters installed by low level RPC2 code. There are two basic modes of use, interactive and command line mode. The command line version are good for almost all common tasks but have less flexibility than the interactive version which gives full control over the filters. The Coda failure emulation package consists of two pieces: a library of routines (libfail) that is linked in with each client and server, and a user interface program (filcon) that controls the behavior of the linked-in libraries. These components allow a wide range of failure scenarios to be emulated, including server failure, network failure, asymmetric and non-transitive communication, and lossy networks. At each client and server, every incoming and outgoing packet is presented to the failure emulation package. Each packet is checked against an ordered list of filters. The first filter whose address matches the IP address on the packet (destination for send filters, or source for receive filters) is used to determine what action should be taken on the packet. A filter consists of three parts: a probability, a predicate, and a delay. The probability specifies what fraction of packets that match the predicate are allowed to pass through unharmed. The delay may be used to delay packets in order to simulate a slow connection to those machines matching the filters address. The delay will apply regardless of the probability. Filters may either apply to incoming (receive) packets or outgoing (send) packets. filcon enables a user to manipulate filters. There are two modes of operating with filcon: short summary command line commands, and interactive use. The interactive user interface presented by filcon is based on the readline (3) and Coda parsing libraries. A command with arguments can be issued in two ways. If only the command name is typed, filcon will prompt the user for the arguments. The command name may be uniquely abbreviated. Alternatively, all the arguments to a command may be given on the command line. If any arguments are missing, the command will fail; there is no partial prompting. This feature is intended to allow the user to produce command scripts.

INTERACTIVE USAGE
Start this mode by typing filcon. The following commands are available.

addclient host port
    Connects to a client at IP port number port on the host named host. (For Coda clients and servers, use 1363 and 1361 respectively.)

deleteclient clientnum
    Disconnects from; client number clientnum.

listclients
    Lists the current set of connected clients.

insertfilter clientnum side id host color lenmin lenmax probability speed
    Inserts a filter into client number clientnum's table on the specified side (one of in out). The filter will be inserted after the existing filter with identifier id. (Inserting after the filter with identifier 0 will insert the filter before all existing filters.) The characteristics of the new filter are host, color, lenmin, lenmax, probability and speed. Host is specified as a name or an IP address of the form "a.b.c.d." Any of the 4 IP components can be wildcarded by specifying a value of -1. Thus "-1.-1.-1.-1" matches any host, while "128.2.-1.-1" matches any host on subnet 2 at CMU. Lenmin and lenmax specify the minimum and maximum RPC packet sizes that match this filter. Color is a number in the range from 0 to 254. A value of -1 specifies that any color matches. RPC2 connections can be colored using the call RPC2_SetColor (). Packets sent out on a connection acquire the color of the connection. Note that reply packets acquire the color of the reply connection, which may be different. Colors are particularly valuable in stressing critical phases of higher-level protocols. By changing connection color between phases, one can easily investigate the effect of failures on specific phases. Probability is specified as an integer in the range from 0 to 10000, and correspond to floating point numbers in the range 0.00 to 1.00. The speed is the speed in bits per second that data should be transmitted between the machines. The value returned from this routine is the filters unique identifier. Speeds other than the default cannot be applied on receive filters.

removefilter clientnum side id
    Removes the filter with identifier id on the given side of client clientnum.

getfilters clientnum
    Lists the filters at client clientnum.

purgeFilters clientnum side
    Removes all filters from the set specified by side. side can be either in, out, or both (the default).

quit
    Terminates the program. Note that this does not clear any filters.

COMMANDLINE INVOCATIONS

filcon isolate
    isolate the servers and clients from all other Coda servers and clients. Servers will still listen to themselves allowing for system administration to proceed on the machine.

filcon join
    This is normally issued after isolate and inserts a matrix of filters to allow communication between the clients and servers listed on the command line.

filcon clear
    Removes all filter from the hosts given.

partition
    blocks traffice between the hosts given.

heal
    removes all of the filters between hostname1 and hostname2 inserted by partition, or slow, or filcon.

slow
    inserts filters on hostname1 and hostname2 to control the network speed between the machines.

ARGUMENTS

port
    Port to attatch to. This should be 1363 for a Coda client and 1361 for a server.

speed
    Speed in bits per second

BUGS
You cannot currently designate a host by IP address of the form a.b.c.d as described above when binding to a process. May confuse the user with the error message ``RPC2_SUCCESS.'' No authentication or security checks are done. Denial of service attacks are trivial, since any user can set up filters on any other client or server.

AUTHOR
Walter Smith, 1988, created. M. Satyanarayanan, 1990, updated. Puneet Kumar, 1990, Created Maria R. Ebling, 1991, updated. Lily Mummert, 1992, Added support for speed. David Steere, 1994, Added "purgeFilters", slight rewrite. Joshua Raiff, 1993, Created man page Peter Braam, 1998, Complete rewrite for filcon.