SSL Orchestrator Collection

F5 SSL Orchestrator (SSLO) is designed and purpose-built to enhance SSL/TLS infrastructure, provide security solutions with visibility into SSL/TLS encrypted traffic, and optimize and maximize the existing security investments.

SSL Orchestrator delivers dynamic service chaining and policy-based traffic steering, applying context-based intelligence to encrypted traffic handling to allow you to intelligently manage the flow of encrypted traffic across your entire security stack, ensuring optimal availability.

F5 Ansible Declarative and Imperative collections enable the users to create required BIG-IP objects, configure and deploy SSL Orchestrator topology.

../_images/f5-dynamic-traffic-steering.png

For more information on SSL Orchestrator, see SSL Orchestrator on F5.com.

Version compatibility matrix

These BIG-IP versions are supported in these Ansible versions.

F5 SSLO Orchestrator F5 Ansible Declarative Collection
7.5.2 >= 1.7.0

Guiding Principles

SSL Orchestrator automation with Ansible requires the following guiding principles:

  • Object relationships
    Similar to Local Traffic Manager (LTM) components, SSL Orchestrator objects have an inherent parent-child relationship with other objects. For example, a security policy applies traffic flows to service chains, thus a defined service chain must exist before the policy is created. In an Ansible playbook this could be as simple as creating the service chain task before the policy task. The notable exception to this rule is Topology creation, which can create all objects in a single process.

    ../_images/f5_sslo_ansible_relationships.png

  • Strictness
    The SSL Orchestrator guided configuration (UI) is a workflow-driven process (i.e. wizard) that creates and manages all objects required for optimal configuration of a topology. This imposes a limitation on the ability to customize a configuration in order to maintain that optimal state, and this limitation is controlled by a strictness mechanism. In the UI, a lock icon represents strictness. Disabling strictness (unlocking the lock) allows for free customization of the different objects, but also moves the burden of configuration state to the administrator. In this Ansible collection, strictness is intentionally disabled for all objects to allow for advanced customization. In some instances, this prevents management of SSL Orchestrator objects from the UI (which in theory should not be necessary if you are relying on automation tools).

  • Reconciliation
    The SSL Orchestrator configuration is managed by a separate JSON-based block structure, independent of the native BIG-IP managed control plane (MCP) process. The SSL Orchestrator control plane then relies on a daemon to reconcile JSON configurations into MCP objects. This reconciliation process produces a short delay between committing a configuration and realization of the respective MCP objects. Thus, an SSL Orchestrator Ansible task will take longer to execute than typical BIG-IP tasks. SSL Orchestrator tasks must also be executed serially (one at-a-time).

SSLO Collection

This section contains an overview of available modules form F5 Ansible Declarative collection support F5 SSL Orchestrator.

Configurations

Module Name Description
bigip_sslo_config_authentication Manage an SSL Orchestrator authentication object
bigip_sslo_config_policy Manage an SSL Orchestrator security policy
bigip_sslo_config_resolver Manage the SSL Orchestrator DNS resolver configuration
bigip_sslo_config_service_chain Manage an SSL Orchestrator service chain
bigip_sslo_config_ssl Manage an SSL Orchestrator SSL configuration
bigip_sslo_config_utility Manage the set of SSL Orchestrator utility functions

Security Services

Module Name Description
bigip_sslo_service_tap Manage an SSL Orchestrator TAP security device
bigip_sslo_service_http Manage an SSL Orchestrator HTTP security device
bigip_sslo_service_icap Manage an SSL Orchestrator ICAP security device
bigip_sslo_service_layer2 Manage an SSL Orchestrator Layer 2 security device
bigip_sslo_service_layer3 Manage an SSL Orchestrator Layer 3 security device
bigip_sslo_service_swg Manage an SSL Orchestrator SWG service

Topologies

Module Name Description
bigip_sslo_config_topology Manage an SSL Orchestrator Topology

Deploying SSLO topology

This example demonstrates deploying SSLO topology using both imperative (f5_modules) and declarative (f5_bigip).

Requirements Installation of both f5_modules and f5_bigip collections into ansible collections directory is required. You can install them with the following commands:

$> ansible-galaxy collection install f5networks.f5_modules

$> ansible-galaxy collection install f5networks.f5_bigip

or if installing declarative collection from development:

$> ansible-galaxy collection install git+https://github.com/F5Networks/f5-ansible-bigip.git#ansible_collections/f5networks/f5_bigip

Example SSLO topology

In this section, we create the relevant objects (VLAN, SNAT Pool, SSL key and Certificate files) on BIG-IP using the imperative collection.

The following is the setup.yaml file.

---
- name: Create a demo topology vlan
  f5networks.f5_modules.bigip_vlan:
    name: "{{ sslo_vlan }}"
    tagged_interface: 1.2
    provider: "{{ provider }}"

- name: Create demo snatpool
  f5networks.f5_modules.bigip_snat_pool:
    name: "{{ snat_pool_name }}"
    members:
    - "172.1.1.1"
    - "172.1.1.2"
    provider: "{{ provider }}"

- name: Create new key and cert
  bigip_command:
    commands:
    - "tmsh create sys crypto key {{ ssl_key }}"
    - "tmsh create sys crypto cert {{ ssl_name }} common-name sslo-test key {{ ssl_key }}"

Next, we create and deploy SSL Orchestrator topology with the relevant services and policy in the following order.

  1. SSLO SSL Configuration
  2. SSLO L3 Service
  3. SSLO ICAP Service
  4. SSLO Service Chain
  5. SSLO Policy
  6. SSLO Topology

Next, we create a vars.yaml to define connection related variables and commonly used variables shared by tasks in the playbook.

## connection specific variables
provider:
    user: "{{ bigip_username }}"
    server: "{{ ansible_host }}"
    server_port: "{{ bigip_port }}"
    password: "{{ bigip_password }}"
    validate_certs: "{{ validate_certs }}"

bigip_username: "admin"
bigip_port: 8443
bigip_password: "admin"
validate_certs: false

ansible_user: "{{ bigip_username }}"
ansible_httpapi_password: "{{ bigip_password }}"
ansible_network_os: "f5networks.f5_bigip.bigip"
ansible_command_timeout: 1800
ansible_httpapi_use_ssl: true
ansible_httpapi_use_proxy: false
ansible_httpapi_validate_certs: "{{ validate_certs }}"
ansible_httpapi_port: "{{ bigip_port }}"
persistent_log_messages: true
f5_telemetry: false

## playbook specific variables
ssl_name: sslo_demo.crt
ssl_key: sslo_demo.key
snat_pool_name: "demo_topology-snat"
sslo_ssl: demo_ssl
sslo_vlan: demo_vlan
sslo_l3: demo_l3
sslo_icap: demo_icap
sslo_chain: demo_schain
sslo_policy: demo_policy
sslo_topo: demo_l3_out

The Playbook main.yaml deploys the SSLO topology.

---
- name: Deploy Demo Topology
  hosts: all
  collections:
    - f5networks.f5_bigip
  connection: httpapi
  vars_files: demo_vars.yaml

tasks:
    - import_tasks: setup.yaml

    - name: Create demo SSLO SSL setting
      bigip_sslo_config_ssl:
        name: "{{ sslo_ssl }}"
        client_settings:
        proxy_type: "reverse"
        cert: "/Common/{{ ssl_name }}"
        key: "/Common/{{ ssl_key }}"

    - name: Create demo Layer 3 service
      bigip_sslo_service_layer3:
        name: "{{ sslo_l3 }}"
        devices_to:
        interface: "1.1"
        tag: 40
        self_ip: "198.19.64.7"
        netmask: "255.255.255.128"
        devices_from:
        interface: "1.1"
        tag: 50
        self_ip: "198.19.64.245"
        netmask: "255.255.255.128"
        devices:
        - ip: "198.19.64.30"
        - ip: "198.19.64.31"
        port_remap: 8080

    - name: Create demo SSLO ICAP service
      bigip_sslo_service_icap:
        name: "{{ sslo_icap }}"
        ip_family: "ipv4"
        devices:
        - ip: "1.1.1.1"
            port: 1344
        - ip: "2.2.2.2"
            port: 1348
        headers:
        enable: yes
        h_from: "foo_from"
        host: "foo_host"
        user_agent: "foo_ua"
        referrer: "foo_referrer"
        enable_one_connect: no
        preview_length: 2048
        service_down_action: "drop"
        allow_http10: yes


    - name: Create demo SSLO service chain
      bigip_sslo_config_service_chain:
        name: "{{ sslo_chain }}"
        services:
        - service_name: "{{ sslo_icap }}"
            type: "icap"
            ip_family: "ipv4"
        - service_name: "{{ sslo_l3 }}"
            type: "L3"
            ip_family: "ipv4"

    - name: Create demo SSLO policy
      bigip_sslo_config_policy:
        name: "{{ sslo_policy }}"
        servercert_check: true
        proxy_connect:
        username: "testuser"
        password: ""
        pool_members:
            - ip: "192.168.30.10"
            port: 100
        policy_rules:
        - name: "demorule"
            match_type: "match_any"
            policy_action: "reject"
            conditions:
            - condition_type: "category_lookup_all"
                condition_option_category:
                - "Financial Data and Services"
                - "General Email"
            - condition_type: "client_port_match"
                condition_option_ports:
                - "80"
                - "90"
            - condition_type: "client_ip_geolocation"
                geolocations:
                - type: "countryCode"
                    value: "US"
                - type: "countryCode"
                    value: "UK"
        - name: "demorule2"
            match_type: "match_all"
            policy_action: "allow"
            conditions:
            - condition_type: "category_lookup_all"
                condition_option_category:
                - "Financial Data and Services"
                - "General Email"
            - condition_type: "client_port_match"
                condition_option_ports:
                - "80"
                - "90"
            service_chain: "{{ sslo_chain }}"

    - name: Create demo SSLO Topology
      bigip_sslo_config_topology:
        name: "{{ sslo_topo }}"
        topology_type: "outbound_l3"
        dest: "192.168.1.4%0/32"
        port: 8080
        ip_family: "ipv4"
        ssl_settings: "{{ sslo_ssl }}"
        security_policy: "{{ sslo_policy }}"
        vlans:
        - "/Common/{{ sslo_vlan }}"
        snat: snatpool
        snat_pool: "/Common/{{ snat_pool_name }}"

This creates the topology as shown in SSLO user interface as seen in the following image.

../_images/topology.png

Known issues

The module bigip_sslo_config_topology currently supports create and delete operations. The Update operation will be supported in a later stage.