Chapter 4: Editing Configurations

This chapter looks at example InControl API based code for performing typical editing operations on a cOS Core configuration. Assuming that we have checked out a configuration, we will examine how typical editing operations can be performed on a cOS Core configuration.

Adding an IP Rule

Let us first look at how a new IP rule is defined and examine in more depth some of the code used in the code example at the beginning of Chapter 2, Starting Coding.

IP rules define what traffic is allowed or dropped as it enters the firewall through a particular interface (the source interface) and exits another interface (the destination interface), and that comes from a particular network (the source network) going to a particular network (the destination network).

In this example, taken from the code example in the previous chapter, we will allow traffic from the network lannet which is connected to the lan interface to flow to the Internet. The Internet is connected to the wan interface and the destination network is all-nets (in other words, any network).

The required IP rule can be summarized as follows:

Action Src Interface Src Network Dest Interface Dest Network Service
NAT lan lannet wan all-nets http-outbound

The code to add this rule is:

Dictionary<string, string> properties = new Dictionary<string, string>();
		
properties.Add("Action", "NAT");
properties.Add("SourceInterface", "lan");
properties.Add("SourceNetwork", "lannet");
properties.Add("DestinationInterface", "wan");
properties.Add("DestinationNetwork", "all-nets");
properties.Add("Service","http-outbound");
properties.Add("LogEnabled","True");
properties.Add("Comments", "Allow/NAT HTTP traffic from LAN to WAN");

Node folder = server.GetRootNode(cfg);

server.AddChildNode(folder, "IPRule", "Example_Drop_Rule", properties);

Breaking the code down, let us examine the individual statements:

The equivalent CLI command would be:

Device:/> add IPRule Action=NAT
			SourceInterface=lan
			SourceNetwork=lannet
			DestinationInterface=wan
			DestinationNetwork=all-nets
			Service=http-outbound
			LogEnabled=True
			Name=NAT_HTTP 

Again, we can see that referring to the CLI command can provide us with the correct parameters that need to be specified when using the InControl API.

Adding an IP4 Address Folder

Let us assume we need to create a new folder called InternalServersFolder to collect together in one place a group of IP4 addresses which are all related to internal servers. We can create the folder with the following code:
Dictionary<string, string> properties = new Dictionary<string, string>();
Node folder = server.AddChildNode(server.GetRootNode(cfg),
		"AddressFolder","InternalServersFolder", properties);
The Node object called folder can now be used in the next step when we add an address to it.

Let us move on to one of the more common operations performed with cOS Core configurations which is manipulating the Address Book. This is where all the symbolic names for IP addresses that cOS Core uses are defined along with their associated IP addresses. Some default address book objects are defined by cOS Core, others may have to be added.

Adding an IP4 Address Object

Next, let us first look at how we add a new IP4 address object to the configuration's address book. Let us assume we want to add a new IP for a web server with the symbolic name webserver_ip and an IP address 10.53.95.1.
Dictionary<string,string> properties = new Dictionary<string,string>();
		
properties["Address"] = "10.53.95.1";
properties["Comments"] = "Web Server Address";

server.AddChildNode(folder, "IP4Address", "webserver_ip", properties);

Let us examine the individual lines in this code:

Let us now examine how this would be done through the CLI to see the similarity:

Device:/> add Address IP4Address webserver_ip
			Address=10.53.95.1
			Comments="Web Server Address"

[Tip] Tip

Thinking about how an operation would be performed with the CLI can often provide a framework for understanding how to do the same operation using the InControl API.

Changing Configuration Settings

Let us now look at changing some existing configuration settings. In this example, we will change the current values of the settings TCPSequenceNumbers and TCPAllowReopen. The code to do this is:
Dictionary<string, string> properties = new Dictionary<string, string>();
		
properties.Add("TCPSequenceNumbers", "Ignore");
properties.Add("TCPAllowReopen", "True");

Node folder = server.GetNode(cfg, "TCPSettings");

server.SetNodeProperties(folder, properties);

Let us look at the individual operations in this code:

In this example, the CLI Reference Guide can once again give us the correct naming for the Node object and its individual settings. TCP Settings is listed as a node (or object) name in the guide and all related settings are listed in that section of the guide.

Listing Configuration Items

To list out the contents of a particular node we can use the following code to enumerate the values and then display them on the console as a list.
foreach(KeyValuePair<string,string> item in server.GetNodeProperties(node))
	{
		Console.WriteLine(item.Key + ":\t" + item.Value);
	}

Deleting Configuration Items

Deleting a node in the configuration is simple:
Server.DeleteNode(node)

The Attribute Value and Deleting Related Objects

An Attribute value can be assigned to configuration objects so that all items with a particular value can be deleted at once. For example, the code above to add an IP rule could become:
properties = new Dictionary<string,string>();
		
properties.Add("Attribute", "user_A");
properties.Add("SourceInterface", "any");
	"
	"
server.AddChildNode(incoming, "IPRule", "Example_Drop_Rule", properties);
Where the string user_A will be assigned as the Attribute for all configuration objects related to this user.

[Note] Note

The Attribute value is not definable with the CLI. The InControl API must be used.

Usage with Security as a Service

A special addition has been made to the InControl API for usage with the Security as a Service (SECaas) feature. Service providers who are building portals using the InControl API may need to force a firewall to search for an updated SECaas license. This is done as shown below.

// The server object is first retrieved
		Domain global = server.get_Root();

// Then the gateway
SecurityGateway sgw =
	server.GetConfigObjectByName(global, "MySGW") as SecurityGateway;

// Finally, the license download is triggered
server.TriggerSECaaSLicenseDownload(sgw);