iControl 101 - #15 - System Services

This installment of iControl 101, I'll focus on the System Service interface where you can have full control of the running state of all the services on the system.

Initialization

This article uses PowerShell and the iControl Cmdlets for PowerShell as the client environment for querying the data.  The following setup will be required for the examples contained in this article.

PS > add-pssnapin icontrolsnapin
PS > initialize-f5.icontrol -HostName theboss -Username admin -Password admin
True
PS > $Services = (Get-F5.iControl).SystemServices

Getting a list of services

Like most other interfaces, the get_list() method takes no parameters as input and returns a list of contained objects.  In this case, it returns a list of System.ServiceType's that are installed on the system.

PS > $Services.get_list()
SERVICE_HTTPD
SERVICE_NTPD
SERVICE_SSHD
SERVICE_SYSLOGD
SERVICE_ALERTD
SERVICE_ASM
SERVICE_BCM56XXD
SERVICE_BIG3D
SERVICE_BIGD
SERVICE_BIGDBD
SERVICE_CHMAND
SERVICE_COMM_SRV
...

Querying the status of services

There are two methods for querying the status of the services on the system.  As illustrated in this example, the get_all_service_statuses() method takes no parameters and returns a list of structures containing the ServiceType in the service field, and the ServiceStatusType in the status field.

PS > $Services.get_all_service_statuses()
                                                    service                                                      status
                                                    -------                                                      ------
                                              SERVICE_HTTPD                                           SERVICE_STATUS_UP
                                               SERVICE_NTPD                                           SERVICE_STATUS_UP
                                               SERVICE_SSHD                                           SERVICE_STATUS_UP
                                            SERVICE_SYSLOGD                                           SERVICE_STATUS_UP
                                             SERVICE_ALERTD                                           SERVICE_STATUS_UP
                                                SERVICE_ASM                                           SERVICE_STATUS_UP
                                           SERVICE_BCM56XXD                                           SERVICE_STATUS_UP
                                              SERVICE_BIG3D                                           SERVICE_STATUS_UP
                                               SERVICE_BIGD                                           SERVICE_STATUS_UP
                                             SERVICE_BIGDBD                                           SERVICE_STATUS_UP
                                             SERVICE_CHMAND                                           SERVICE_STATUS_UP
                                           SERVICE_COMM_SRV                                         SERVICE_STATUS_DOWN
                                           ...

If you are concerned with a single service, or even a small subset of services, you can use the get_service_status() method that takes as input an array of ServiceTypes and returns, like the get_all_service_statuses() method, an array of structures containing the ServiceType and ServiceStatusType values for each requested service.

PS > $Services.get_service_status( ("SERVICE_HTTPD", "SERVICE_ASM") )
                                                    service                                                      status
                                                    -------                                                      ------
                                              SERVICE_HTTPD                                           SERVICE_STATUS_UP
                                                SERVICE_ASM                                           SERVICE_STATUS_UP

Controlling services

Querying the status of a service is nice, but the real fun is stopping or restarting a service.  The set_service() method takes as input an array of ServiceType's and a single ServiceStatusType to assign to all of those services.  The below example will stop the eventd service and then query the eventd service's status to verify that the action worked.  I then call set_service() again, this time enabling the service and querying the get_service_status() method to verify that it's back up.

PS C:\> $Services.set_service( (,"SERVICE_EVENTD"), "SERVICE_ACTION_STOP")
PS > $Services.get_service_status( (,"SERVICE_EVENTD") )
                                                    service                                                      status
                                                    -------                                                      ------
                                             SERVICE_EVENTD                                         SERVICE_STATUS_DOWN

PS > $Services.set_service( (,"SERVICE_EVENTD"), "SERVICE_ACTION_START")
PS > $Services.get_service_status( (,"SERVICE_EVENTD") )
                                                    service                                                      status
                                                    -------                                                      ------
                                             SERVICE_EVENTD                                           SERVICE_STATUS_UP

There may be a situation where you want to restart all running services.  This can be accomplished with the set_all_services method.  It takes as input the ServiceStatusType you would like to set and applies it to all of the services.  This is equivalent to calling the set_service() method passing in the list of ServiceTypes returned from the get_list() method.

PS > $Services.set_all_services("SERVICE_ACTION_RESTART")

Start, Stop, and Restart are not the only controls you can use.  There are also Reinit, Add to Boot List, Remove from Boot List, Add to Default List, and Remove from Default List.  The values are defined in the following table.

SERVICE_ACTION_START     0     Start a service.
SERVICE_ACTION_STOP     1     Stop a service.
SERVICE_ACTION_REINIT     2     Reinitialize a service.
SERVICE_ACTION_RESTART     3     Restart a service by stopping and starting the service
SERVICE_ACTION_ADD_TO_BOOT_LIST     4     Add a service to the boot/reboot list. If on this list, the service will be started on bootup and stopped on reboot.
SERVICE_ACTION_REMOVE_FROM_BOOT_LIST     5     Remove a service from the boot/reboot list. If on this list, the service will be started on bootup and stopped on reboot.
SERVICE_ACTION_ADD_TO_DEFAULT_LIST     6     Add a service to the default action list.
SERVICE_ACTION_REMOVE_FROM_DEFAULT_LIST     7     Remove a service from the default action list.

So, if you never want to see the TMM running again, then you can call set_service_status on SERVICE_TMM with SERVICE_ACTION_STOP and SERVICE_ACTION_REMOVE_FROM_BOOT_LIST and you'll be all set.  Warning, doing so will disable almost all functionality on the BIG-IP so it's not recommended.

Controlling Remote Access

There are a couple of methods controlling the ssh service.  Specifically you can query and set the enabled/disabled state of specific client addresses.  The get_ssh_access_v2() method will return an array of states and a address list for each entry in the restriction list.

PS > $Services.get_ssh_access_v2()
                                                      state addresses
                                                      ----- ---------
                                              STATE_ENABLED {ALL}

If you want to add a restriction for a specific client address, you can do so with the set_ssh_access_v2() method that takes as input a SSHAccess_v2 structure containing the EnabledState and array of addresses for that state.  This example will disable ssh access from client address 10.10.10.10 and verifies the call succeeded.  It then will overwrite the previous entry with enabled access for all client addresses.  The special value of "ALL" can be used for all addresses.

PS > $SSHAccess = New-Object -TypeName iControl.SystemServicesSSHAccess_v2
PS > $SSHAccess.state = "STATE_DISABLED"
PS > $SSHAccess.addresses = (, "10.10.10.10")
PS > $Services.set_ssh_access_v2($SSHAccess)
PS > $Services.get_ssh_access_v2()
                                                      state addresses
                                                      ----- ---------
                                             STATE_DISABLED {10.10.10.10}

PS > $SSHAccess.state = "STATE_ENABLED"
PS > $SSHAccess.addresses = (, "ALL")
PS > $Services.set_ssh_access_v2($SSHAccess)
PS > $Services.get_ssh_access_v2()
                                                      state addresses
                                                      ----- ---------
                                              STATE_ENABLED {ALL}

Rebooting the System

In the rare case that you need to reboot your system, the System.Services interface can help.  The reboot_system() method takes as input a number of seconds until reboot.  This method call is equivalent to the /usr/bin/delayedReboot command line program on the BIG-IP.

PS C:\> $Services.reboot_system(5)

Conclusion

With the System.Services interface, you have full control of what services are running on the system, and control to enable or disable them at your whim.  Use this power wisely as it could have adverse effects if you disable a service that you are relying on running.