Managing Objects

5. Managing Objects

Three object types

Contents

Three object types
Objects properties
Creating an object
Editing Service objects
Objects Choosers
Objects literal value
Objects dependancies
Deleting an object
Predefined objects
Objects cut/copy/paste
Groups of objects
Conditional values
Automatic values

In a filtering rule, the action (pass, block, ...) is performed on an IP packet if it meets certain conditions. Some of these conditions are the interface the packet in passing through, its source and destination addresses, its protocol and source and destination ports for tcp or udp packets, or its ICMP-type and ICMP-code for ICMP packets.

Isba uses three types of objects to represent these conditions: Interfaces, Host/Nets and Services. When building a rule, you will paste one (or more) objects in purpose-built boxes, e.g. the From and To boxes will accept to receive hosts and/or nets, etc. In Nat rules the hosts and nets objects can go to Original From, Original To and Translated Address boxes.

Objects properties

All three kinds of objects have the following properties:

a name
a value
a color
a one line comment.

Services have two additional properties:

a protocol (tcp, udp, tcp/udp, icmp or any other IP protocol)
a second value to optionally specify the end of a port range or an ICMP-Code.

You can define or change your objects' properties in edition windows. To open the edition window of an object, double-click on it. For example:

Objects properties

Editing a host or net object

All properties are optional, except that an object must have at least a name or a value. If an object has a value but no name, this value will appear in the ruleset: use such anonymous objects when you want to see constants. For example, if you want to see 127.0.0.1 instead of a name, define the following object:

Anonymous objects

Sample anonymous object

On the opposite, objects may be given a name but no value. At compile time, isba will generate an error unless it is a well-known object, such as for example the ftp service (see below).

This feature allows you to start writing a ruleset prior to knowing the values of all your objects.

Unvalued objects

Sample unvalued object

An object's Value field may receive the name of another object. In that case both objects have the same literal value. More interesting, the Value field may receive the names of several objects: see Groups of objects.

"Variable" objects

Creating an object

You can create an object from several places:

from the 'Objects' main menu (New ...)
from the Chooser (New)
"on the fly": from main window, with a right-clic on a rule (new ...), in the box you want to put the future object in
from main window, with a shift-clic on the Hosts/Nets, Services or Interfaces button in the upper-right corner.

These four methods all open an clean object edition window.

Gui tips

If you close the Edition window before clicking Create or Update, your changes will be lost.

Editing Service objects

Note that in the Service edit window above, there is an entry box for one value only. Apparently you cannot enter the second value needed to define a port range. In actual fact the second field is only needed in TCP, UDP,TCP/UDP and ICMP protocols. For ICMP it receives the ICMP-Code (if any) and for the other three it receives the upper bound (if any) of the port range. The Service edition window dynamically shows the second field only if the protocol entered is one of the four quoted above.

Editing Service objects

The Protocol field may be defined by either typing in the protocol name, or its number, or by using a popup menu (right-clic in the entry field). This menu allows you to choose among the four protocols quoted above and all the protocols found in the local /etc/protocols file.

Specifying the protocol

The TCP, UDP and TCP/UDP port ranges may be one of four kinds: a single port, a standard port range, and one-bound ranges (low bounded and high bounded). The following table explains how to define these four kinds of ranges. Note the particular way of specifying the low-bounded range. Also note that outbound ranges (e.g.: port 2000 <> 3000, ports outside the 2000-3000 range) are not supported by isba.

Defining a TCP, UDP or TCP/UDP port range

Range kind	First value ('Port')	Second value ('To')	Example
single port	the port value	(empty)	port = 23
dual-bounded range	the lower bound (exclusive)	the upper bound (exclusive)	port 5999 >< 6011
high-bounded range	(empty)	the upper bound (exclusive)	port < 1024
low-bounded range	the lower bound (exclusive)	65536	port > 1023

If you choose ICMP in the Protocol area, the two following fields are respectively the 'ICMP-Type' and the optional 'ICMP-Code'. Like the Protocol, those fields may be entered manually, by typing the ICMP type or code number (or the ipfilter keywords), or by using the right-clic popup menu. As the ICMP-Codes available depend on the ICMP-Type chosen, the ICMP-Code right-clic popup menu contents depend on the value you chose for the ICMP-Type. On the following screenshot, the Service 'ICMP Host Unreachable' have been defined, and the popup menus are shown together to illustrate this point.

Defining an ICMP Service

Sample ICMP Service edition window with popups

Objects Choosers

Gui tips

In Choosers, the objects properties are shown in descending order of interest: if you need to see only the Name, you can reduce the window width until only the Name column is visible. You won't see all bottom buttons any more, but the same functions (New, Edit, Eval, Del, Where) are available from the right-clic popup menu. This is a way of saving screen space if it is a problem.

The objects you create are managed in three lists: one Interfaces list, one Hosts/nets list and one Services list. Each objects list is browseable in a Chooser window. You can open a Chooser either from the Objects main menu, or by clicking on one of the three buttons in the upper-right corner, or by right-clicking on a rule box.

The Choosers show all objects properties: the Name (with the object color), the Value, the Comment, and the file the object was included from, if any. The Chooser for Services objects also shows the protocol.

Sample Chooser window

From the Chooser window you can:

select an object by clicking it: the object is copied to the clipboard, from where it an be pasted in the ruleset
create an object (New)
edit the selected object (Edit)
see the literal value of an object (Eval)
destroy the selected object (Del)
see where an object is used (Where).

Gui tips

The New, Edit, Eval, Del and Where functions are also available from a right-click on an object (popup menu).

Seeing the literal value of an object

At any time you can see the literal value of an object in the Eval window: its IP address and mask if it's a net or host, its port range if it's a tcp or udp service, etc. This feature is interesting for group objects: you see the set of literal values a group contains.

Gui tips

The Eval window is dynamic: you can keep it open and clic on several objects, and their literal value will show up when you click them.

Sample object evaluation window

As an object may be defined as a function of other objects, up to any recursion level, there may happen to be a cycle in the definition graph. This is an error condition as the value of all objects involved in the cycle can't be computed. In this case the Eval window displays 'CYCLIC' in its value field.

"CYCLIC" literal value

With isba you can (temporarily) define objects as having no value. The Eval window displays 'UNDEF' for undefined objects. The same thing applies to objects whose value is a function of an undefined object.

"UNDEF" literal value

Seeing objects dependancies

The 'Where' button in Choosers opens a popup window that allows you to see where the currently selected object (call it A) is used:

Objects dependancies

which objects use object A in their value - recursively (which objects use an object that uses A, etc)
which ipf and nat rules use object A (or an object that uses A, etc).

Gui tips

In the Where window you can double-clic on an object or rule to go straight to it (as with the 'Show me' button).

You get a dual-column list where the first columns is the type of location where object A is used (is it an interface, a host/net, a service, an ipf rule or a nat rule), and the second column is the name of the object or the number of the rule.

When you select one of these locations and clic the 'Show me' button, isba takes you straight to that location: if it's an object, its edition window is opened, and if it's a rule, it is shown (ruleset is scrolled) in main window.

"Show me" button

Sample Where window

Deleting an object

The 'Del' button in Choosers open a popup window that is exactly a 'Where' window with the addition of a 'Delete' button. Being a confirmation popup, it lets you decide whether to delete the object or not, depending on where it is used. If the 'Where' window is empty, you can safely delete the object. If the object is used in some objects or rules, it will be removed from the latter.

Note that included objects can't be deleted (the Delete button is disabled). If you don't want an included object anymore, you must delete it from the file it is defined in (open the include fine).

Deleting an object

When your object is ready to be created (or updated), holding down the Shift key while clicking the Create (or Update) button, results in the edit window staying open and retaining its data. This is useful to enter several similar objects.

Similarly, if you hold down the Control key, the edition window will stay open but will be cleared.

Creating many objects one after the other

Predefined objects

When you create a new isba ruleset, the following objects are predefined for the sake of convenience:

Predefined objects

Object	Description
proto-tcp	a port-undefined TCP Service you can use in an Ipf rule to say "proto tcp" without specifying a port
proto-udp	a port-undefined UDP Service you can use in an Ipf rule to say "proto udp" without specifying a port
proto-tcp-udp	you'll never guess
proto-icmp	a type-undefined ICMP Service you can use in an Ipf rule to say "proto icmp" without specifying an ICMP-Type/Code
0/32	in Nat rules, specifies the current IP address
0/0	in Nat rules, specifies any original address
lo0	the local loopback interface

Moreover, at compile time, isba tries to resolve values of undefined objects:

undefined tcp/udp Services are given the port number and protocol from the local machine's /etc/services file, if found
undefined protocols are given the value from /etc/protocols, if found
undefined hosts are given the value from /etc/hosts, if found.

At compile time, for each undefined object which value is found that way, isba prints a warning on stdout.

Note: using such undefined objects makes your ruleset depend on the local machine's /etc/services, protocol and/or hosts files, which may not be a good idea.

Objects cut/copy/paste

Cut, copy, paste

Objects can be cut, copied and pasted. This is the way you place objects in rules: you first copy them in Choosers, then you paste them in rules.

See also how you can copy objects from one ruleset to another.

Gui tips

A left-click on an object in a rule or in a chooser copies it. The object flashes to show it is in the clipboard (exception: in a Chooser, objects don't flash).

A control-click on an object in a rule cuts it: the object is removed from the rule and is copied to the clipboard.
A control-clic on an object in a Chooser is a synonym of deletion (clipboard is unchanged). That is to say, isba opens a 'Where' window that shows where the object is used, then you have to click on the 'Delete' button to really destroy it. Note that if the object come from an include file, the 'Delete' button is greyed, because you can't destroy included objects.

If an object is in the clipboard, a middle-click on a box in a rule pastes it if it is the right object kind (you don't want to paste an Interface object in the From column). If the box already contains objects, you middle-click one of the objects, say 'B', and the pasted object is inserted just after 'B'. You can reorder objects in a box in this way by cutting and pasting.

Groups of objects

We have seen that the value of an object may be a literal value or the name of another object. Actually it can be any number of literal values and objects names, so you can define a "group object". A group object may contain names of other group objects. Group objects are managed in the same Chooser as simple objects of the same kind (there's no special Chooser for groups).

Groups of objects

Sample group object

At any time you can see the literal value of a group object.

Conditional values

In multi-targets rulesets you can make the value of an object depend on the target the ruleset is compiled for. The syntax is:

#if-target(hosts_nets, value1 [, value2])

At compile time, the object which value is entered as above has its value equal to value1 if the target the ruleset is compiled for belongs to hosts_nets. Otherwise its value is value2 if present, or nothing if value2 is not defined (as if the object didn't exist).

#if-target()
#if-not-target()

In hosts/nets objects, value1 and value2 may be given the value 'any'.

There is also a '#if-not-target()' directive with the same syntax.

Automatic values

In multi-targets rulesets, and if remote management is set up, interfaces and hosts objects may receive a target-dependent value at compile time.

An Interface object can be given the value #from-ifconfig or #from-ifconfig(N): it receives the name of the Nth interface found in the target machine's `ifconfig -a` (lo0 excepted) at compile time. Isba uses the remote management SSH channel to get it. The syntax for the interface value is (default value for N is 1):

interface value = #from-ifconfig [(N)]

A Host object can be given the value #from-ifconfig(intf_name): it receives the IP address of the interface named intf_name (read from target machine's ifconfig -a through SSH) at compile time. The syntax for the host value is:

#from-ifconfig[(N)]
#from-ifconfig(intf)

host value = #from-ifconfig(intf_name)

Currently automatic values are supported in Solaris and *BSD.