GeoIP Register Update¶
Overview¶
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.
Finally, use the GeoIP Update Manager API to distribute and apply the GeoIP updates from the BIG-IQ to the specified BIG-IPs.
Warning
You cannot use this API to modify an existing DB File object. If you try to register a DB File that already exists, the GeoIP Register Update API will fail.
REST Endpoint: /mgmt/cm/device/geoip/task/register-update¶
Requests¶
POST /mgmt/cm/device/geoip/task/register-update¶
Send a POST to the /task/register-update collection to register GeoIP update package files with the BIG-IQ.
Query Parameters¶
None
Request Parameters¶
The JSON in the body of the POST request can contain the following parameters. You can specify a single pair of update files.
| Name | Type | Required | Description |
|---|---|---|---|
| filePath | string | True | Path with name of the GeoIP Database update package ZIP file. Do not try to rename this file. |
| validationFilePath | string | True | Path with name of the checksum file of the package. Do not try to rename this file. |
Response¶
The JSON in the response can contain the following parameters.
HTTP/1.1 200 OK
| Name | Type | Description |
|---|---|---|
| currentStep | string | The current step in the task. If the task has finished, the value can be “FINISHED”. If there has been an error in the task, the value can indicate the step with the error. |
| endDateTime | string | The time this task ended. |
| errorMessage | string | A message describing an error that has caused to the task to fail. The message field can contain a displayable description of this error. |
| filePath | string | Path with name of the GeoIP Database update package ZIP file. |
| id | string | The UUID for the task. |
| identityReferences | array | An array of objects which reference identities. |
| link | string | The URL of the identity. |
| message | string | A displayable message about an error causing task failure. The errorMessage field can contain a more technical description of this error. |
| nextStep | string | The next step in the task. If the task has finished, the value can be “FINISHED”. If there has been an error in the task, the value of currentStep can indicate the step with the error. |
| ownerMachineId | object | Machine id of the BIG-IQ. |
| packageFileName | string | A name for the update package BIG-IQ sets for internal use only. |
| selfLink | string | URL for this task. You can poll for the status of this task by sending GET requests to this url. |
| startDateTime | string | The time this task started. |
| status | string | The task’s status. Initially the response to the POST can be “STARTED” and can eventually update to “FINISHED” or “FAILED”. You can poll for the updated status of this task by sending GET requests to the selfLink. |
| username | string | The name of the user. |
| userReference | object | Reference to the user. |
| link | string | The URL of the user. |
| validationFilePath | string | Path with name of the checksum file of the package. |
Permissions¶
| Role | Allow |
|---|---|
| device_manager | Yes |
GET /mgmt/cm/device/geoip/task/register-update¶
To retrieve a list of all tasks, send a GET request to the task/register-update 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 response can contain the following parameters.
HTTP/1.1 200 OK
| Name | Type | Description |
|---|---|---|
| currentStep | string | The current step in the task. If the task has finished, the value can be “FINISHED”. If there has been an error in the task, the value can indicate the step with the error. |
| dbFile | object | A reference to the new DB File object that represents the input files. This field can be absent if the task failed. |
| id | string | UUID of the referenced DB File object. |
| link | string | URL of the GeoIP database file. |
| name | string | The database version in the referenced DB File object’s update package. |
| endDateTime | string | The time this task ended. |
| errorMessage | string | A message describing an error that has caused to the task to fail. The message field can contain a displayable description of this error. |
| finalFilePath | string | The final path with name of the GeoIP Database update package ZIP file. BIG-IQ moves the file from the original location provided to a final location. This field can be absent if the task failed. |
| finalValidationFilePath | string | The final path with name of the checksum file of the package. BIG-IQ moves the file from the original location provided to a final location. This field can be absent if the task failed. |
| filePath | string | Path with name of the GeoIP Database update package ZIP file. |
| id | string | The UUID for the task. |
| identityReferences | array | An array of objects which reference identities. |
| link | string | The URL of the identity. |
| message | string | A displayable message about an error causing task failure. The errorMessage field can contain a more technical description of this error. |
| nextStep | string | The next step in the task. If the task has finished, the value can be “FINISHED”. If there has been an error in the task, the value of currentStep can indicate the step with the error. |
| ownerMachineId | object | Machine id of the BIG-IQ. |
| packageFileName | string | A name for the update package BIG-IQ sets for internal use only. |
| selfLink | string | URL for this task. You can poll for the status of this task by sending GET requests to this url. |
| startDateTime | string | The time this task started. |
| status | string | The task’s status. Initially the response to the POST can be “STARTED” and can eventually update to “FINISHED” or “FAILED”. You can poll for the updated status of this task by sending GET requests to the selfLink. |
| username | string | The name of the user. |
| userReference | object | Reference to the user. |
| link | string | The URL of the user. |
| validationFilePath | string | Path with name of the checksum file of the package. |
Examples¶
POST to create a register-update task¶
The following example sends a POST request to create a new register-update task.
POST https://<BIG-IQ>/mgmt/cm/device/geoip/task/register-update
The JSON in the body of the POST can look similar to the following example.
{
"filePath": "/shared/images/ip-geolocation-v2-2.0.0-20200106.421.0.zip",
"validationFilePath": "/shared/images/ip-geolocation-v2-2.0.0-20200106.421.0.zip.md5"
}
Response¶
The response to the POST can contain the id and status of the task. The initial value of status can be “STARTED”. The JSON in the body of the response to a GET after the task has finished and was successful can look similar to the following.
HTTP/1.1 200 OK
{
"filePath": "/shared/images/ip-geolocation-1.0.1-20190610.386.0.zip",
"validationFilePath": "/shared/images/ip-geolocation-1.0.1-20190610.386.0.zip.md5",
"packageFileName": "ip-geolocation-1.0.1-20190610.386.0.zip",
"id": "e0be3d36-a4a1-4412-8b89-93bc3523c9af",
"kind": "cm:device:geoip:task:register-update:devicegeoipregisterupdatetaskworkerstate",
"status": "STARTED",
"selfLink": "https://localhost/mgmt/cm/device/geoip/task/register-update/e0be3d36-a4a1-4412-8b89-93bc3523c9af",
"username": "admin",
"generation": 5,
"startDateTime": "2020-02-19T11:48:02.604-0800",
"userReference": {
"link": "https://localhost/mgmt/shared/authz/users/admin"
},
"ownerMachineId": "2de94d24-df05-4fb6-926f-5fb56a9799fc",
"lastUpdateMicros": 1582141683396944,
"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” or “FAILED”. For this example, the placeholder <id> can be replaced by the value e0be3d36-a4a1-4412-8b89-93bc3523c9af.
GET https://<BIG-IQ>/mgmt/cm/device/geoip/task/register-update/<id>
After the task finishes, the value of status in the response changes to “FINISHED” and the JSON in the body of the response can look similar to the following.
{
"filePath": "/shared/images/ip-geolocation-1.0.1-20190610.386.0.zip",
"validationFilePath": "/shared/images/ip-geolocation-1.0.1-20190610.386.0.zip.md5",
"finalFilePath": "/shared/geoip/ip-geolocation-1.0.1-20190610.386.0.zip",
"finalValidationFilePath": "/shared/geoip/ip-geolocation-1.0.1-20190610.386.0.zip.md5",
"packageFileName": "ip-geolocation-1.0.1-20190610.386.0.zip",
"dbFile": {
"id": "746fede8-24c4-4191-9b46-083c15ddfb64",
"kind": "cm:device:geoip:dbfile:geoipdbfilestate",
"link": "https://localhost/mgmt/cm/device/geoip/dbfile/746fede8-24c4-4191-9b46-083c15ddfb64",
"name": "1.0.1-20190610.386.0"
},
"id": "e0be3d36-a4a1-4412-8b89-93bc3523c9af",
"kind": "cm:device:geoip:task:register-update:devicegeoipregisterupdatetaskworkerstate",
"status": "FINISHED",
"currentStep": "FINISHED",
"nextStep": "FINISHED",
"selfLink": "https://localhost/mgmt/cm/device/geoip/task/register-update/e0be3d36-a4a1-4412-8b89-93bc3523c9af",
"username": "admin",
"generation": 5,
"endDateTime": "2020-02-19T11:48:03.347-0800",
"startDateTime": "2020-02-19T11:48:02.604-0800",
"userReference": {
"link": "https://localhost/mgmt/shared/authz/users/admin"
},
"ownerMachineId": "2de94d24-df05-4fb6-926f-5fb56a9799fc",
"lastUpdateMicros": 1582141683396944,
"identityReferences": [{
"link": "https://localhost/mgmt/shared/authz/users/admin"
}]
}
If the task fails, the response to the GET can contain a status of “FAILED”. If there has been an error in the task, the value of currentStep can indicate the step with the error and the values of message and errorMessage can describe the error. The JSON in the body of the response can look similar to the following example.
{
"filePath": "/shared/images/ip-geolocation-bad-checksum.zip",
"validationFilePath": "/shared/images/ip-geolocation-bad-checksum.zip.md5",
"message": "Error: Failed to verify Update package file \"/shared/images/ip-geolocation-bad-checksum.zip\": calculated checksum didn't match MD5 checksum file \"/shared/images/ip-geolocation-bad-checksum.zip.md5\".",
"errorMessage": "Error: Failed to verify Update package file \"/shared/images/ip-geolocation-bad-checksum.zip\": calculated checksum didn't match MD5 checksum file \"/shared/images/ip-geolocation-bad-checksum.zip.md5\".",
"id": "58a1a860-49f0-4262-bdba-2de4a2dcc3db",
"kind": "cm:device:geoip:task:register-update:devicegeoipregisterupdatetaskworkerstate",
"status": "FAILED",
"currentStep": "VALIDATE_PACKAGE",
"nextStep": "PREPARE_FILES",
"selfLink": "https://localhost/mgmt/cm/device/geoip/task/register-update/58a1a860-49f0-4262-bdba-2de4a2dcc3db",
"username": "admin",
"generation": 2,
"endDateTime": "2020-02-19T11:45:33.051-0800",
"startDateTime": "2020-02-19T11:45:32.527-0800",
"userReference": {
"link": "https://localhost/mgmt/shared/authz/users/admin"
},
"ownerMachineId": "2de94d24-df05-4fb6-926f-5fb56a9799fc",
"lastUpdateMicros": 1582141533101690,
"identityReferences": [{
"link": "https://localhost/mgmt/shared/authz/users/admin"
}]
}
GET to list all register-update tasks¶
The following example sends a GET request to retrieve a list of all tasks.
GET https://<BIG-IQ>/mgmt/cm/device/geoip/task/register-update
DELETE to delete a register-update task¶
The following example sends a DELETE request to delete a single register-update task. In the following example, replace the placeholder <id> with the value of the id for the task.
DELETE https://<BIG-IQ>/mgmt/cm/device/geoip/task/register-update/<id>