Managing the bonding connection

The bonding connection, also called as the port trunking or link aggregation, which means combining several network interfaces (Only OSA card supporty by Crypto-Appliance) to a single link.

REST APIs of Crypto-Appliance can be used to config the bonding connection.

Config the bonding connection by REST APIs

REST APIs usage are based on SSC Document IBM_Secure_Service_Container_REST_APIs_latest.pdf.

Configing the Bonding interface can be done by REST APIs of the Appliance, there is a precondition:

Prerequisites: One permanent or temporary OSA/HiperSockets card (works in layer3 mode) is required to already configure on the Appliance. Through this existing interface, REST APIs of the Appliance can be accessed to operate Bonding Connection management. After the Bonding interface is created successfully, the existing temporary card can be removed from the appliance.

Figure showing the Bonding Connection

Figure 1. The Bonding Connection

1. Get the access-token and accept license

Install jq tool before execute the following scripts.


# Get access token by user and password

appliance_ip="a.b.c.d"
admin_user="root"
admin_pass="password"

req_json=$(cat << EOF
{
   "kind": "request",
   "parameters":{
      "user":"${admin_user}",
      "password":"${admin_pass}"
   }
}
EOF
)

auth_token=$(curl -k -X POST https://${appliance_ip}/api/com.ibm.zaci.system/api-tokens -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json' -d "${req_json}" | jq -r .parameters.token)

# Accept license before do any Bonding interface management

req_json=$(cat << EOF
{
   "kind": "request",
   "parameters":{
      "accept": true
   }
}
EOF
)

curl -k -X PUT https://${appliance_ip}/api/com.ibm.zaci.system/software-license -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json' -H "Authorization: Bearer ${auth_token}" -d "${req_json}"

2. Get all unconfigured OSA devices on the Appliance

Get all exsiting unconfigured OSA devices from the Appliance.

appliance_ip="a.b.c.d"
auth_token="xxxxx"

curl -k -X GET "https://${appliance_ip}/api/com.ibm.zaci.system/network-device?configured=0&&type=OSA" -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json' -H "Authorization: Bearer ${auth_token}"

3. Get the DeviceIds

From step-2 returned devices list, found two devices of which chpid are NOT the same, and remember the deviceIds, like 0.0.b400 with chip 31 and 0.0.bc09 with chpid 32.

    {
      "deviceIds": [
        "0.0.b400",
        "0.0.b401",
        "0.0.b402"
      ],
      "chpid": "31",
      "card_type": "OSD_1000",
      "port": 0,
      "state": "unconfigured",
      "self": "/api/com.ibm.zaci.system/network-device/0.0.b400"
    },
    {
      "deviceIds": [
        "0.0.bc09",
        "0.0.bc0a",
        "0.0.bc0b"
      ],
      "chpid": "32",
      "card_type": "OSD_1000",
      "port": 0,
      "state": "unconfigured",
      "self": "/api/com.ibm.zaci.system/network-device/0.0.bc09"
    },

4. Create a Bonding network interface

Create a new bonding network interface based on the DeviceIds of step-3, such as 0.0.b400 and 0.0.bc09.

Note: The CHPIDs of slaves cannot be the same, and there can be multiple slaves added into one bonding connection.

SSC Appliance supports to create 3 modes of bonding network interface, as the following links:

  1. Create a active-backup bonding network interface

  2. Create a 802.3ad bonding network interface

  3. Create a round-robin bonding network interface

4.1. Create an active-backup bonding network interface

Note: The following code snippet is an example, you can refer to the REST API document for more details.

appliance_ip="a.b.c.d"
auth_token="xxxxx"

bonding_conn_name="xxxxx"
bonding_conn_id="bondx"  # x - it is a number, like 0, 1, 2

slave1_device_id="0.0.xxxx"  # like '0.0.b400'
slave2_device_id="0.0.yyyy"  # like '0.0.bc09'
primary_device_id="${slave1_device_id}" # define the primary device

# define slave1 json object
slave1=$(cat << EOF
{
  "id": "${slave1_device_id}",
  "bus_id": "${slave1_device_id}",
  "portno": 0
}
EOF
)

# define slave2 json object
slave2=$(cat << EOF
{
  "id": "${slave2_device_id}",
  "bus_id": "${slave2_device_id}",
  "portno": 0
}
EOF
)

# define active-backup optional parameters
optional_params=$(cat << EOF
{
  "primary": "${primary_device_id}",
  "primary_reselect": "always",
  "num_grat_arp": 0,
  "fail_over_mac": "none"
}
EOF
)

# define bonding connection json object
req_json=$(cat << EOF
{
  "kind": "request",
  "resource-name": "network-connection",
  "resource-version": "1.0",
  "parameters": {
    "device": "${bonding_conn_name}",
    "name": "${bonding_conn_id}",
    "type": "bond",
    "bond_params": {
      "mode": "active-backup",
      "monitoring": {
        "monitor_type": "mii",
        "miimon": 100,
        "downdelay": 0,
        "updelay": 0
      },
      "slaves": [${slave1},${slave2}],
      "optional_params": ${optional_params}
    },
    "ipv4_method": "disabled",
    "ipv6_method": "disabled",
    "activate_connection": "yes"
  }
}
EOF
)


curl -k -X POST https://${appliance_ip}/api/com.ibm.zaci.system/network-connection/v1 -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json' -H "Authorization: Bearer ${auth_token}"  -d "${req_json}"

4.2. Create an 802.3ad bonding network interface

Note: The following code snippet is an example, you can refer to the REST API document for more details.

appliance_ip="a.b.c.d"
auth_token="xxxxx"

bonding_conn_name="xxxxx"
bonding_conn_id="bondx"  # x - it is a number, like 0, 1, 2

slave1_device_id="0.0.xxxx"  # like '0.0.b400'
slave2_device_id="0.0.yyyy"  # like '0.0.bc09'

# define slave1 json object
slave1=$(cat << EOF
{
  "id": "${slave1_device_id}",
  "bus_id": "${slave1_device_id}",
  "portno": 0
}
EOF
)

# define slave2 json object
slave2=$(cat << EOF
{
  "id": "${slave2_device_id}",
  "bus_id": "${slave2_device_id}",
  "portno": 0
}
EOF
)

# define 802.3ad optional parameters
optional_params=$(cat << EOF
{
  "lacp_rate": "fast",
  "xmit_hash_policy": "layer2+3"
}
EOF
)

# define bonding connection json object
req_json=$(cat << EOF
{
  "kind": "request",
  "resource-name": "network-connection",
  "resource-version": "1.0",
  "parameters": {
    "device": "${bonding_conn_id}",
    "name": "${bonding_conn_name}",
    "type": "bond",
    "bond_params": {
      "mode": "802.3ad",
      "monitoring": {
        "monitor_type": "mii",
        "miimon": 100,
        "downdelay": 0,
        "updelay": 0
      },
      "slaves": [${slave1},${slave2}],
      "optional_params": ${optional_params}
    },
    "ipv4_method": "disabled",
    "ipv6_method": "disabled",
    "activate_connection": "yes"
  }
}
EOF
)


curl -k -X POST https://${appliance_ip}/api/com.ibm.zaci.system/network-connection/v1 -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json' -H "Authorization: Bearer ${auth_token}"  -d "${req_json}"

4.3. Create a round-robin bonding network interface

Note: The following code snippet is an example, you can refer to the REST API document for more details.

appliance_ip="a.b.c.d"
auth_token="xxxxx"

bonding_conn_name="xxxxx"
bonding_conn_id="bondx"  # x - it is a number, like 0, 1, 2

slave1_device_id="0.0.xxxx"  # like '0.0.b400'
slave2_device_id="0.0.yyyy"  # like '0.0.bc09'

# define slave1 json object
slave1=$(cat << EOF
{
  "id": "${slave1_device_id}",
  "bus_id": "${slave1_device_id}",
  "portno": 0
}
EOF
)

# define slave2 json object
slave2=$(cat << EOF
{
  "id": "${slave2_device_id}",
  "bus_id": "${slave2_device_id}",
  "portno": 0
}
EOF
)

# define bonding connection json object
req_json=$(cat << EOF
{
  "kind": "request",
  "resource-name": "network-connection",
  "resource-version": "1.0",
  "parameters": {
    "device": "${bonding_conn_id}",
    "name": "${bonding_conn_name}",
    "type": "bond",
    "bond_params": {
      "mode": "balance-rr",
      "monitoring": {
        "monitor_type": "mii",
        "miimon": 100,
        "downdelay": 0,
        "updelay": 0
      },
      "slaves": [${slave1},${slave2}],
      "optional_params": {}
    },
    "ipv4_method": "disabled",
    "ipv6_method": "disabled",
    "activate_connection": "yes"
  }
}
EOF
)


curl -k -X POST https://${appliance_ip}/api/com.ibm.zaci.system/network-connection/v1 -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json' -H "Authorization: Bearer ${auth_token}"  -d "${req_json}"

4.4. Self url

Remember the returned self url is the created interface resource, as in the following example:

[{
  "kind": "response",
  "parameters": {
    "self": "/api/com.ibm.zaci.system/network-connection/v1/bond0"
  }
}]

5. Configure the ipv4 address

Configure the ipv4 address for the newly created bonding connection interface.

appliance_ip="a.b.c.d"
auth_token="xxxxx"
interface_url="/api/com.ibm.zaci.system/network-connection/v1/bond0"
ipv4_address="x.x.x.x"
ipv4_gateway="x.x.x.x"

req_json=$(cat << EOF
{
    "kind":"request",
    "resource-name":"network-connection",
    "resource-version":"1.0",
    "parameters":{
        "portno":0,
        "name":"crypot-appliance-test",
        "activate_connection":"yes",
        "ipv4_method":"manual",
        "ipv4_addresses":[
            "${ipv4_address}/22"
        ],
        "ipv4_gateway":"${ipv4_gateway}",
        "ipv6_method":"disabled"
    }
}
EOF
)

curl -k -X PUT https://${appliance_ip}${interface_url} -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json' -H "Authorization: Bearer ${auth_token}"  -d "${req_json}"

6. Reboot the Appliance

A newly created network interface is not supported by the webservice immediately (Rest APIs on this IP do not work), and requires to reboot the Appliance to make the new network interface supported by the webservice.

appliance_ip="a.b.c.d"
auth_token="xxxxx"

curl -k -X PUT https://${appliance_ip}/api/com.ibm.zaci.system/appliance/reboot -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json' -H "Authorization: Bearer ${auth_token}"

7. Delete a network interface

Delete a network interface by using the id.

appliance_ip="a.b.c.d"
auth_token="xxxxx"
network_if_id="bond1"

curl -k -X DELETE https://${appliance_ip}/api/com.ibm.zaci.system/network-connection/v1/${network_if_id} -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json' -H "Authorization: Bearer ${auth_token}"

7. Get all network interfaces on the Appliance

Get all exsiting network interfaces on the Appliance.

appliance_ip="a.b.c.d"
auth_token="xxxxx"

curl -k -X GET https://${appliance_ip}/api/com.ibm.zaci.system/network-connection/v1 -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json' -H "Authorization: Bearer ${auth_token}"