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:
properties = new Dictionary<string,string>();
properties.Add("SourceInterface", "lan");The parameter name SourceInterface and all possible parameters for the rule can be found under IPrule in the cOS Core CLI Reference Guide.
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);Notice how we specify the rule set by using the suffix IPRuleSet to qualify the name. If we wanted to add a new IP rule set called, for example User-rules, we would use the code:
Node new_ruleset = server.AddChildNode(root, "IPRuleSet", "User-rules", null);
server.AddChildNode(folder, "IPRule", "NAT_HTTP", properties);The NAT_HTTP parameter will be the symbolic name of the rule used in the configuration.
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:
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);Here, we use the Node object called folder which was defined at the beginning of this chapter.
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 |
---|---|
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:
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);
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 |
---|---|
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);