GeoIP Update Manager¶

Overview¶

Use the GeoIP Update Manager API to distribute and apply the GeoIP updates from the BIG-IQ to the BIG-IPs. This API cannot be used to update a BIG-IP with a GeoIP Database update package that does not apply to that BIG-IP version. The GeoIP Update Manager API uses the latest-released DB File object. After applying an update to a BIG-IP, this API will not re-apply the same update package to that BIG-IP the next time the task is run.

Use the GeoIP Register Update API to register GeoIP update package files with the BIG-IQ. Before using the GeoIP Register Update API, download the GeoIP DB update file package from F5 . The GeoIP DB update file package can contain a ZIP file and MD5 file. For example, you can manually download the files to your computer using SCP or any other file transfer tool and then copy them to the BIG-IQ.

You can use the GeoIP DB File API to get or delete a GeoIP DB File object. You cannot use the GeoIP DB File API with POST, PUT or PATCH operations. To create a GeoIP DB File object, use the GeoIP Register Update API.

You can use the GeoIP Config API to query GeoIP configuration settings, such as delayTimeBetweenBigips which specifies the number of seconds to wait before updating the next BIG-IP in a sequence of multiple BIG-IPs.

REST Endpoint: /mgmt/cm/device/geoip/task/update-manager¶

Requests¶

POST /mgmt/cm/device/geoip/task/update-manager¶

To create a task which the adds the latest updates to all applicable BIG-IPs, send a POST request to the task/update-manager endpoint specifying just { }, without any fields. To process one or more particular updates, or one or more specific BIG-IPs, specify the relevant objects in the dbFiles list or devices list, respectively.

Query Parameters¶

None

Request Parameters¶

The JSON in the body of the POST request can contain the following parameters.

Name	Type	Required	Description
devices	array	False	A list of BIG-IP URIs for the BIG-IPs to be processed. If not specified, the task updates all managed BIG-IPs on this BIG-IQ. These are the BIG-IPs in the device group: cm-bigip-allBigIpDevices. If a BIG-IP is specified, but there are no GeoIP Database update packages which apply to that BIG-IP’s version, then no changes will be made to that BIG-IP.
link	string	False	URL of BIG-IP.
dbFiles	array	False	A list of links to the GeoIP DB File URIs for the update packages to be processed. If not specified, the task will find and process all the GeoIP Database update packages that are currently relevant.
link	string	False	URL of the GeoIP database file.

Response¶

The JSON in the response can contain the following parameters.

HTTP/1.1 200 OK

Name	Type	Description
id	string	The UUID for the task.
identityReferences	array	An array of objects which reference identities.
link	string	The URL of the identity.
ownerMachineId	object	Machine id of the BIG-IQ.
selfLink	string	URL for this task.
startDateTime	string	The time this task started.
status	string	The task’s status. For example: “STARTED”, “FINISHED”, “QUEUED” or “FAILED”.
username	string	The name of the user.
userReference	object	Reference to the user.
link	string	The URL of the user.

Permissions¶

Role	Allow
device_manager	Yes

GET /mgmt/cm/device/geoip/task/update-manager¶

To retrieve a list of all tasks, send a GET request to the /task/update-manager endpoint without specifying the id. To retrieve a single task, include the task’s id. You can poll for the updated status of this task by sending GET requests to the selfLink.

Request Parameters¶

None

Query Parameters¶

None

Response¶

The JSON in the GET response can contain a list of tasks and the following parameters.

HTTP/1.1 200 OK

Name	Type	Description
actionsPerformed	array	A list of all child tasks started by this task.
link	string	The URL of a child task, and its result, started by this task.
currentstep	string	The current step in the process.
devicesNotNeedingUpdate	number	The number of BIG-IPs that did not need to be updated because they have already had the GeoIP Database installed.
endDateTime	string	The time this task ended.
id	string	The UUID for the task.
identityReferences	array	An array of objects which reference identities.
link	string	The URL of the identity.
nextStep	string	The task’s next step.
numericProgress	number	An index of the task’s progress.
ownerMachineId	object	Machine id of the BIG-IQ.
selfLink	string	URL for this task.
startDateTime	string	The time this task started.
status	string	The task’s status. For example: “STARTED”, “FINISHED”, “QUEUED” or “FAILED”.
successfulUpdates	number	The number of actions that completed successfully.
totalActions	number	The total number of actions performed by this task. If any BIG-IP devices already had the applicable GeoIP Database installed, this can be less than the total number of devices specified.
username	string	The name of the user.
userReference	object	Reference to the user.
link	string	The URL of the user.

Permissions¶

Role	Allow
Device_Common_Viewer	Yes
device_manager	Yes

DELETE /mgmt/cm/device/geoip/task/update-manager/<id>¶

To delete a task, you can send a DELETE request specified by the task’s identifier, <id>.

Request Parameters¶

None

Query Parameters¶

None

Response¶

HTTP/1.1 200 OK

The JSON in the body of the response is for the deleted item.

Permissions¶

Role	Allow
device_manager	Yes

Examples¶

POST to create a task¶

The following example sends a POST request to create a new task.

POST https://<BIG-IQ>/mgmt/cm/device/geoip/task/update-manager

The JSON in the body of the POST can look similar to the following example.

{
    "dbFiles": [{
                    "link": "https://localhost/mgmt/cm/device/geoip/dbfile/0e0a83af-1e2f-45c0-8238-7a044477d996"
            },
            {
                    "link": "https://localhost/mgmt/cm/device/geoip/dbfile/0ea9aa97-8b97-40d7-8fba-986baae09ac1"
            }
    ],
    "devices": [{
            "link": "https://localhost/mgmt/shared/resolver/device-groups/cm-bigip-allBigIpDevices/devices/d2d32b49-50d5-4f0a-bdf1-59d6731b5a21"
    }]
}

Response¶

The response to the POST can contain the id and status of the task. Only one task can be running at a time, and the initial status of the task can be “STARTED” or “QUEUED”. The JSON in the body of the initial response to the POST can look similar to the following.

HTTP/1.1 200 OK

{
    "id": "f54364ae-3f73-41d6-8018-a6e8111a8337",
    "kind": "cm:device:geoip:task:update-manager:devicegeoipupdatemanagertaskworkerstate",
    "status": "STARTED",
    "selfLink": "https://localhost/mgmt/cm/device/geoip/task/update-manager/f54364ae-3f73-41d6-8018-a6e8111a8337",
    "username": "admin",
    "generation": 7,
    "startDateTime": "2020-01-14T13:48:00.531-0800",
    "userReference": {
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "ownerMachineId": "97db1a0f-024a-4ea7-b036-9ce6bf00d645",
    "lastUpdateMicros": 1579038482423278,
    "identityReferences": [{
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    }]
}

You can then poll to check for completion of the task by sending GET requests to the endpoint specified by id until the value of status in the response changes to “FINISHED”. For this example, the placeholder <id> can be replaced by the value f54364ae-3f73-41d6-8018-a6e8111a8337.

GET https://<BIG-IQ>/mgmt/cm/device/geoip/task/update-manager/<id>

After the task finishes successfully, the value of status in the response can be “FINISHED”.

HTTP/1.1 200 OK

{
    "id": "f54364ae-3f73-41d6-8018-a6e8111a8337",
    "kind": "cm:device:geoip:task:update-manager:devicegeoipupdatemanagertaskworkerstate",
    "status": "FINISHED",
    "dbFiles": [{
            "link": "https://localhost/mgmt/cm/device/geoip/dbfile/872b950d-902e-42d2-8809-809314c5a07f"
    }],
    "devices": [],
    "message": "All BIG-IP Device updates have completed successfully.",
    "nextStep": "FINISHED",
    "selfLink": "https://localhost/mgmt/cm/device/geoip/task/update-manager/f54364ae-3f73-41d6-8018-a6e8111a8337",
    "username": "admin",
    "generation": 7,
    "currentStep": "FINISHED",
    "endDateTime": "2020-01-14T13:49:02.373-0800",
    "startDateTime": "2020-01-14T13:48:00.531-0800",
    "userReference": {
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "ownerMachineId": "97db1a0f-024a-4ea7-b036-9ce6bf00d645",
    "lastUpdateMicros": 1579038482423278,
    "identityReferences": [{
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    }],
    "numericProgress": 100,
    "devicesNotNeedingUpdate": 0,
    "totalActions": 3,
    "successfulUpdates": 3,
    "actionsPerformed": [{
                    "link": "https://localhost/mgmt/cm/device/geoip/task/push-update/15a3dec8-9fe8-42e7-9f9a-b6a5203e22bf"
            },
            {
                    "link": "https://localhost/mgmt/cm/device/geoip/task/push-update/6dccba03-9736-4ff1-bcef-9625288e6b8c"
            },
            {
                    "link": "https://localhost/mgmt/cm/device/geoip/task/push-update/74fee852-1bde-47c7-8bba-0ea6dc30bd81"
            }
    ]
}

If the task has finished partially unsuccessful, the value of status in the response can be “FINISHED” with message describing the error.

HTTP/1.1 200 OK

{
    "id": "f54364ae-3f73-41d6-8018-a6e8111a8337",
    "kind": "cm:device:geoip:task:update-manager:devicegeoipupdatemanagertaskworkerstate",
    "status": "FINISHED",
    "dbFiles": [{
            "link": "https://localhost/mgmt/cm/device/geoip/dbfile/872b950d-902e-42d2-8809-809314c5a07f"
    }],
    "devices": [],
    "message": "2 of 3 BIG-IP Device updates have completed successfully; 1 failed.",
    "nextStep": "FINISHED",
    "selfLink": "https://localhost/mgmt/cm/device/geoip/task/update-manager/f54364ae-3f73-41d6-8018-a6e8111a8337",
    "username": "admin",
    "generation": 42,
    "currentStep": "FINISHED",
    "endDateTime": "2020-02-24T13:51:23.545-0800",
    "startDateTime": "2020-02-24T13:50:34.013-0800",
    "userReference": {
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "ownerMachineId": "2de94d24-df05-4fb6-926f-5fb56a9799fc",
    "lastUpdateMicros": 1582581083596074,
    "identityReferences": [{
            "link": "https://localhost/mgmt/shared/authz/users/admin"
    }],
    "numericProgress": 100,
    "devicesNotNeedingUpdate": 0,
    "totalActions": 3,
    "successfulUpdates": 2,
    "actionsPerformed": [{
                    "link": "https://localhost/mgmt/cm/device/geoip/task/push-update/2014616e-db9b-4717-9fe3-c562e93e1d11"
            },
            {
                    "link": "https://localhost/mgmt/cm/device/geoip/task/push-update/26da1e5c-1399-46b5-acaf-f3150ec788c6"
            },
            {
                    "link": "https://localhost/mgmt/cm/device/geoip/task/push-update/8f58b7e3-7a45-4226-9762-c580c08bcec9"
            }
    ]
}

GET to get all tasks¶

The following example sends a GET request to retrieve a list of all tasks.

GET https://<BIG-IQ>/mgmt/cm/device/geoip/task/update-manager

Response¶

HTTP/1.1 200 OK

The JSON in the body of the response represents a list of tasks.

DELETE to delete a task¶

The following example sends a DELETE request to a single task. In the following replace the placeholder <id> with the value of the id of the task.

DELETE https://<BIG-IQ>/mgmt/cm/device/geoip/task/update-manager/<id>

Response¶

HTTP/1.1 200 OK

The JSON in the body of the response represents the deleted task.

Previous Next