Men&Mice Integration Pack

Introduction

This pack provides integration with the Men&Mice IPAM SOAP API. Actions within this pack mirror one-for-one the "Commands" in the SOAP API. Data types and payloads also mirror one-for-one.

Quick Start

1. Install the pack

   st2 pack install menandmice

2. Execute an action (example: list all DNS Zones)

   st2 run menandmice.get_dns_zones server=menandmice.domain.tld username=administrator password=xxx

Configuration

The configuration for this pack is used to specify connection information for all Men&Mice servers you'll be communicating with. The location for the config file is /opt/stackstorm/config/menandmice.yaml.

Note : st2 pack config doesn't handle schemas refernences very well (known bug) so it's best to create the configuraiton file yourself and copy it into /opt/stackstorm/configs/menandmice.yaml then run st2ctl reload --register-configs

Schema

---
menandmice:
  <connection-name-1>:
    server: <hostname or ip of the Men&Mice server>
    username: <[email protected] (preferred) or domain\username>
    password: <password for username>
  <connection-name-2>:
    server: <hostname or ip of the Men&Mice server>
    username: <[email protected] (preferred) or domain\username>
    password: <password for username>
    port: <port number override to use for the connections: default = None (defaults to 80/443)>
    transport: <transport override to use for the connections: default = http'>
    wsdl_endpoint: <HTTP URL for the M&M WSDL: default = '_mmwebext/mmwebext.dll?wsdl'>
  <connection-name-3>:
    ... # note: multiple connections can be specified!

Schema Examples

---
menandmice:
  dev:
    server: menandmice.dev.domain.tld
    username: [email protected]
    password: DevPassword
  stage:
    server: menandmice.stage.domain.tld
    username: [email protected]
    password: stagePassword
    port: 8080
  prod:
    server: menandmice.prod.domain.tld
    username: [email protected]
    password: SuperSecret
    transport: https

Note : All actions allow you to specify a connection name parameter that will reference the conneciton information in the config. Alternatively all actions allow you to override these connection parameters so a config isn't required. See the Actions for more information.

Actions

Actions in this pack are auto-generated from the Men&Mice IPAM SOAP API operations defined in the WSDL file (note: we store these WSDLs in the etc/ directory of this pack). There is an action created for every "Command" in the Men&Mice API. Input and output parameters should be the same with all action names and action parameters convert from CamelCase to snake_case. Example: SOAP command AddDNSServer will be converted to snake_case for the action to become menandmice.add_dns_server. In this same command one of the arguments is dnsServer that becomes the dns_server action parameter.

Usage - Basic

The following example demonstrates running the menandmice.get_dns_zones action using connection information specified as action input parameters.

$ st2 run menandmice.get_dns_zones server=menandmice.domain.tld username=administrator password=xxx
.................
id: 59555e63a814c0698925a1aa
status: succeeded
parameters:
  filter: 'type: Master'
  password: '********'
  server: menandmice.domain.tld
  username: administrator
result:
  exit_code: 0
  result:
    dnsZones:
      dnsZone:
      - adIntegrated: true
        adPartition: null
        adReplicationType: null
        authority: '[Active Directory - domain.tld]'
        customProperties: null
        dnsScopeName: null
        dnsViewRef: null
        dnsViewRefs:
          ref:
          - '{#2-#1}'
          - '{#2-#2}'
        dnssecSigned: false
        dynamic: true
        kskIDs: null
        name: 2.1.10.in-addr.arpa.
        ref: '{#1-#234}'
        type: Master
        zskIDs: null
    totalResults: 1
  stderr: ''
  stdout: ''

The basic example is great and allows for quick testing from the commandline and/or one-off commands in a workflow. However, specifying the same connection information over/over can become tedious and repetitive, luckyily there is a better way.

Usage - Config Connection

This pack is designed to store commonly used connection information in the pack's config file located in /opt/stackstorm/config/menandmice.yaml. The connection info is specified in the config once, and then referenced by name within an action and/or workflow.

Using the action from the basic example, we can enter this connection information in our config:

$ cat /opt/stackstorm/configs/menandmice.yaml
---
menandmice:
  prod:
    server: menandmice.domain.tld
    username: administrator
    password: xxx

Now we can reference this connection (by name) when executing our action:

$ st2 run menandmice.get_dns_zones connection=prod
...

This pays off big time when running multiple commands in sequence.

Usage - Login Sessions

By default this pack performs a login operation in every action if the session parameter is not passed in. To avoid these repetitive logins under the hood we can perform the login operation and then re-use the login session cookie in all subsequent actions within a workflow.

Note: When using a cached login session you still need to pass in a server parameter either as an action parameter or as part of the connection. Without the server we can't build the WSDL URL necessary to establish a SOAP connection to the server.

version: '2.0'

menandmice.wf_login_sessions:
  description:
  input:
    - connection
    - server
    - username
    - password
    - port
    - transport
  output:
    - dns_servers
    - master_dns_zones
  tasks:
    main:
      action: std.noop
      on-success:
        - login
        - get_dns_servers
        - get_dns_zones

    login:
      action: menandmice.login
      input:
        connection: "{{ _.connection }}"
        server: "{{ _.server }}"
        username: "{{ _.username }}"
        password: "{{ _.password }}"
        port: "{{ _.port }}"
        transport: "{{ _.transport }}"
      publish:
        session: "{{ task('login').result.result.session }}"
      on-error:
        fail

    get_dns_servers:
      workflow: menandmice.get_dns_servers
      input:
        session: "{{ _.session }}"
        server: "{{ _.server }}"
      publish:
        dns_servers: "{{ task('get_dns_servers').result.result.dnsServers.dnsServer }}"

    get_dns_zones:
      workflow: menandmice.get_dns_servers
      input:
        session: "{{ _.session }}"
        server: "{{ _.server }}"
        filter: "type:Master"
      publish:
        master_dns_zones: "{{ task('get_dns_zones').result.result.dnsZones.dnsZone }}"

For an even more extensive example see actions/workflows/wf_add_dns_zone.yaml

Usage - Complex Object Types

Many of the actions in the SOAP API take a complex object type as an input parameter. For example we're going to look at the SOAP command AddDNSRecords that maps to the action menandmice.add_dns_records. This command takes an argument dnsRecords with a datatype of ArrayOfDNSRecord. To facilitate this all command arguments that take complex object types map to action arguments of type object. This means that the data passed into this parameter can be a python dict or list, making it work like a native datastructure within workflows. Also, on the commandline using st2 run we an specify these type of objects using a JSON string that will then be auto-converted into a python dict or list when the commandline argument is parsed.

Navigating the SOAP documentation can be a little cumbersome, so to help users out we've insert the expected object structure in the description for these complext data type parameters. These object structures are described in JSON format for easy reading and understandability. We hope this helps!

In the example below you can see both how the JSON string input works for st2 run along with what the datastructure looks like as an input parameter.

$ st2 run menandmice.add_dns_records server=menandmice.domain.tld username=administrator password=xxx dns_records='{"dnsRecord": [ {"name": "testserver.domain.tld.", "type": "A", "data": "10.1.2.100", "enabled": true, "dnsZoneRef": "{#1-#234}" } ] }'
..
id: 59556158a814c03b10b9999
status: succeeded
parameters:
  dns_records:
    dnsRecord:
    - data: 10.1.2.100
      dnsZoneRef: '{#1-#234}'
      enabled: true
      name: testserver.domain.tld.
      type: A
  password: '********'
  server: menandmice.domain.tld
  username: administrator
result:
  exit_code: 0
  result:
    errors: null
    objRefs:
      ref:
      - '{#11-#1271}'
  stderr: ''
  stdout: ''

Usage - Additional Actions

In addition to the auto-generated actions described above, there are a handful of higher-level workflow actions that implement common functionality.

remove_dns_record: Action will find the DNS record and get any related records(CNAME, AAAA, etc) tied to that record and the pointer record. Then remove all the records so that there are no orphaned records left behind. Once the records are removed we then flush the cache for just the records that were removed.

$ st2 run menandmice.remove_dns_record server=menandmice.domain.tld username=administrator password=xxx name="test-name" dns_domain="domain.tld" ip_address='1.1.1.1'
.................
id: 5cca09f449b3d27e56a56cca
action.ref: menandmice.remove_dns_record
parameters:
  dns_domain: domain.tld
  ip_address: 1.1.1.1
  name: test-name
  password: '***'
  server: menandmice.domain.tld
  username: administrator
status: succeeded

resolve_fqdn: Action accepts a name and a DNS Zone reference. Action will find the zone and append that to the name givin returning a FQDN.

$ st2 run menandmice.resolve_fqdn server=menandmice.domain.tld username=administrator password=xxx name="test-name" dns_zone_ref='{#4-#4}'
....
id: 5ccaed9149b3d27e56a56d07
action.ref: menandmice.resolve_fqdn
parameters:
  dns_zone_ref: '{#4-#4}'
  name: test-name
  password: '***'
  server: menandmice.domain.tld
  username: administrator
status: succeeded
start_timestamp: Thu, 02 May 2019 13:16:01 UTC
end_timestamp: Thu, 02 May 2019 13:16:07 UTC

test_credentials: Action will attempt to log into the Men & Mice Server with the credential provided to test if logins are successfull or failed.

$ st2 run menandmice.test_credentials server=menandmice.domain.tld username=administrator password=xxx name="test-name"
...
id: 5cc9f09749b3d27e56a56baa
action.ref: menandmice.test_credentials
parameters:
  password: '***'
  server: menandmice.domain.tld
  username: administrator
status: succeeded (5s elapsed)
result_task: main
result:
  exit_code: 0
  result:
    session: JfY0AgQCMhjuDyKjDOrc
  stderr: ''
  stdout: ''

test_hostname: Action will check to see if a hostname is available for use or not in the DNS Domain. Action will Fail if the hostname is already taken and Succeed if the hostname is available for use. Taken name:

$ st2 run menandmice.test_hostname server=menandmice.domain.tld username=administrator password=xxx hostname='test-name' dns_domain='domain.tld'
.....
id: 5cc9f35449b3d27e56a56c8d
action.ref: menandmice.test_hostname
parameters:
  dns_domain: domain.tld
  hostname: test-name
  password: '***'
  server: menandmice.domain.tld
  username: administrator
status: failed
start_timestamp: Wed, 01 May 2019 19:28:20 UTC
end_timestamp: Wed, 01 May 2019 19:28:30 UTC

Available name:

$ st2 run menandmice.test_hostname server=menandmice.domain.tld username=administrator password=xxx hostname='test-name-2' dns_domain='domain.tld'
.....
id: 5cc9f35449b3d27e56a56c8d
action.ref: menandmice.test_hostname
parameters:
  dns_domain: domain.tld
  hostname: test-name-2
  password: '***'
  server: menandmice.domain.tld
  username: administrator
status: succeeded
start_timestamp: Wed, 01 May 2019 19:28:20 UTC
end_timestamp: Wed, 01 May 2019 19:28:30 UTC

For another example see actions/workflows/wf_add_dns_zone.yaml. The build_master_zone: task creates a DNSZone object and publishes it to the master_zone variable. Then in the add_master_zone: task we pass the DNSZone object master_zone into the dns_zone parameter for the menandmice.add_dns_zone action.

Version Compatiblity

Future

• Create sensors to trigger events on changes (look at the the GetHistory command)