ACC and Docker must be installed prior to the first use. See Installing ACC for instructions.

Running a Conversion

Run the converter by using one of the following commands, replacing the ACC version where necessary:

1. Linux-based systems and Mac, using the following syntax: docker run --rm -v  "$PWD":/app/data f5-as3-config-converter:x.x.x -o data/<output-file-name>.json -u data/<input-ucs-file-name>.ucs
For example: docker run --rm -v  "$PWD":/app/data f5-as3-config-converter:x.x.x -o data/output.json -u data/myucs.ucs
Windows, use the following syntax: docker run --rm -v %cd%:/app/data f5-as3-config-converter:x.x.x -o data/<output-file-name>.json -u data/<input-ucs-file-name>.ucs
For example: docker run --rm -v  %cd%:/app/data f5-as3-config-converter:x.x.x -o data/output.json -u data/myucs.ucs

Note

The source UCS/SCF file must be located in the CURRENT directory to run the command line from the example. The data/myucs.ucs entry refers to a directory inside the container.

If you are using Windows, and you receive a message such as:
Error response from daemon: Drive has not been shared.,
Error loading conf/SCF file, please check the filepath., or
Error extracting specified UCS, please check the file path.
You may need to share the drive or update your shared drive credentials.
See Troubleshooting ACC for more information.

2. Run ACC as a REST-API service. Service runs on port 8080 inside the container, or you can map it to any port on your local OS.
For example: docker run --rm -v "$PWD":/app/data -p 8080:8080 f5-as3-config-converter:1.0.0  serve
Call it with: curl localhost:8080/as3converter -X POST  --form "ucs=@<input-ucs-file-name>.ucs" --form "output=<output-file-name>.json" --form "verbose=true" |jq .

Using Postman to POST to ACC Endpoint

../_images/ACC-POST1.png

Input is bigip confguration called toConvert.conf. Output is file as3Output.json.

After post:

../_images/ACC-POST2.png

curl localhost:8080/as3converter -X POST --form "ucs=@<input-ucs-file-name>.ucs" --form "output=<output-file-name>.json" --form "verbose=true" |jq .

Notes:
Any client similar to Postman can also be used.
Max file size to be processed is 1GB.

Docker Command Line Options

  • docker run portion of the command starts the container.
  • –rm option removes the container after it exits from running the application. Without this the container will persist after it exits and you may have to run a command such as docker container prune to remove leftover containers.
  • The application is located in the /app directory of the container.
  • -v option maps the current directory to the /app/data directory in the container. This is used to read input and write output with the container. In this example we assume the input UCS file and the output JSON file will be read from and written to the current directory.
  • -p option maps the tcp port inside container to the local OS port.

ACC command Line Options

  • -o option specifies the output file name. You must specify this as being in the data directory (with the Docker -v option). When the output file is written in the container it is written to the /app/data directory of the container which maps back to the current directory outside of the container where output.json will actually be written.
  • -u option specifies a UCS file for the application to read. For either .conf or SCF files, use the -c flag. This must be specified as being in the data directory (as specified with the -v option). When the input file is read by the application, it is read from the /app/data directory of the container which maps back to the current directory outside of the container where input file is actually read. This flag is required and you must use only one option of -u or -c, depending on your input file.
  • –recognized option logs to stdout a list of configuration objects that ACC recognized.
  • –recognized-objects option logs to specified file of objects (JSON format) that were recognized.
  • –supported option logs to stdout a list of configuration objects that ACC will convert.
  • –supported-objects option logs to specified file of objects (JSON format) that were converted.
  • –unsupported option logs to stdout a list of configuration objects that ACC did not convert. Note: Objects that will never receive AS3 support are filtered out of this list.
  • –unsupported-objects option logs to specified file of objects (JSON format) that were not converted. Note: Objects that will never receive AS3 support are filtered out of this list.
  • –summary option logs to stdout counts of each generated class.
  • –disable-analytics option will disable usage reporting. All data is anonymized, and this option is enabled by default.
  • –controls option adds debugging “Controls” stanza to declaration.
  • –safety-net option allows a user to bypass fatal conversion errors and generate a best-effort declaration. Accepts a boolean parameter, and defaults to true.
  • -v option filters output by the virtual server name specified. Only this virtual server and dependent objects will be posted to the resulting file.
  • -a option puts the virtual server to specific application. Works only if the -v option is specified. The original VS application is used if this option not specified.
  • -t option puts the virtual server to specific tenant. Works only if -v option specified. The original VS tenant is used if this option not specified.
  • REST-API usage related options when the container is started with serve option. –verbose prints more details in the REST-API response.

Note

The 3 options of -v, -a and -t typically work together with -a and -t having the ability to work independently. If -v is used, then all other virtual servers are ignored. If -t is used, then the virtual server will be placed into this tenant name, even if it was originally in /Common/. If -a is used, then the original virtual server will be placed under the application name specified. By default the virtual server name will be used as the application.

Examples

Original VS    /Common/VS1
    1) only -a /Common/VS1 provided:
        "Common": {
            "class": "tenant",
            "VS1": {
                    "class": "application"
                     "VS1": {
                    .........................
                     {
        2) -t My_tenant  in addition to -v
        "My_tenant": {
            "class": "tenant",
            "VS1": {
                    "class": "application"
                     "VS1": {
                    .........................
                    {
        3) -a "My_application"
        "My_tenant": {
            "class": "tenant",
            "My_aplication": {
                    "class": "application"
                     "VS1": {
                    .........................
                    {

Testing the Results

The best way to test the results is to take the output file and POST the AS3 declaration to a BIG-IP. If the declaration fails, look closely at the error messages, which should provide information on the part of the declaration needing attention.

If you attempt to run ACC, and it provides an unexpected error message, it is likely an issue with the parser and the development team wants to hear about it.
1. Navigate to ACC GitHub.
2. Click New issue > choose the Issue type of Bug report, click Get started.
3. Give the submission a title then fill out the template, attaching files if applicable.
4. When finished, click Submit new issue.

Example

In this section we show a simple BIG-IP configuration from a UCS file, the command to convert, the response from the container, and finally the resulting AS3 declaration output.

The following is the relevant portion of our example UCS file named acc.ucs.

TMSH-VERSION: 13.1.0.8

ltm pool /Common/testaccPool {
    monitor /Common/testaccMonitor
}
ltm virtual /Common/testaccVip {
    destination /Common/192.0.2.14:80
    ip-protocol tcp
    mask 255.255.255.255
    pool /Common/testaccPool
    profiles {
        /Common/tcp { }
        /Common/testaccHTTP { }
    }
    source 0.0.0.0/0
    translate-address enabled
    translate-port enabled
}
ltm virtual-address /Common/192.0.2.14 {
    address 192.0.2.14
    arp enabled
    mask 255.255.255.255
    traffic-group /Common/traffic-group-1
}

ltm monitor http /Common/testaccMonitor {
    adaptive disabled
    defaults-from /Common/http
    destination *:*
    interval 30
    ip-dscp 0
    recv none
    recv-disable none
    send "GET /\r\n"
    time-until-up 0
    timeout 91
}
ltm profile http /Common/testaccHTTP {
    app-service none
    defaults-from /Common/http
    proxy-type reverse
    redirect-rewrite matching
}

This UCS file is put in the same directory from which we are running the container. In the following example, the container is run using a Windows machine:

C:\Users\jordan\Desktop\acc\dist>docker run --rm -v %cd%:/app/data f5-as3-config-converter:1.0.0 -o data/output.json -u data/acc.ucs --summary
1118 configuration objects detected
31 objects are recognized by AS3
12 objects are supported by acc
Generated Declaration { Pool: 1,
Monitor: 1,
HTTP_Profile: 1 }

Once it has run through the converter, the resulting AS3 declaration looks like this:

Example by Application

In this section, we show a simple BIG-IP configuration from a UCS file, the command to convert extracting a single virtual server, the response from the container and the resulting AS3 declaration output.

The following is the relevant portion of our example UCS file named acc.ucs, the virtual we extract is named f5-big-ip and we place it into a tenant named Ten and an application Appl. If the tenant is not specified, ACC uses the original tenant name; if the application is not specified, the AS3 application uses the virtual name.

TMSH-VERSION: 13.1.0.8

ltm pool /Common/testaccPool {
    monitor /Common/testaccMonitor
}
ltm virtual /Common/testaccVip {
    destination /Common/192.0.2.14:80
    ip-protocol tcp
    mask 255.255.255.255
    pool /Common/testaccPool
    profiles {
        /Common/tcp { }
        /Common/testaccHTTP { }
    }
    source 0.0.0.0/0
    translate-address enabled
    translate-port enabled
}
ltm virtual-address /Common/192.0.2.14 {
    address 192.0.2.14
    arp enabled
    mask 255.255.255.255
    traffic-group /Common/traffic-group-1
}

ltm monitor http /Common/testaccMonitor {
    adaptive disabled
    defaults-from /Common/http
    destination *:*
    interval 30
    ip-dscp 0
    recv none
    recv-disable none
    send "GET /\r\n"
    time-until-up 0
    timeout 91
}
ltm profile http /Common/testaccHTTP {
    app-service none
    defaults-from /Common/http
    proxy-type reverse
    redirect-rewrite matching
}
ltm virtual /Custom/testaccVip {
    destination /Common/192.0.2.14:80
    ip-protocol tcp
    mask 255.255.255.255
    pool /Common/testaccPool
    profiles {
        /Common/tcp { }
        /Common/testaccHTTP { }
    }
    source 0.0.0.0/0
    translate-address enabled
    translate-port enabled
}
ltm virtual-address /Custom/192.0.2.14 {
    address 192.0.2.14
    arp enabled
    mask 255.255.255.255
    traffic-group /Common/traffic-group-1
}

ltm monitor http /Custom/testaccMonitor {
    adaptive disabled
    defaults-from /Common/http
    destination *:*
    interval 30
    ip-dscp 0
    recv none
    recv-disable none
    send "GET /\r\n"
    time-until-up 0
    timeout 91
}
ltm profile http /Common/testaccHTTP {
    app-service none
    defaults-from /Common/http
    proxy-type reverse
    redirect-rewrite matching
}

This UCS file is put in the same directory from which we are running the container, which in the following example, is running on a Windows machine:

Note

For more information on command line usage, see the ACC command line options: section above.

C:UsersjordanDesktopaccdist>docker run –rm -v %cd%:/app/data f5-as3-config-converter:1.2.0 -o data/output.json -u data/acc.ucs -v /Custom/testaccVip -a Appl -t Ten –summary
8 BIG-IP objects detected total
6 BIG-IP objects recognized by AS3
8 BIG-IP objects supported by acc
3 AS3 stanzas generated
{ Monitor: 1, Pool: 1, Service_HTTP: 1 }

Once it has run through the converter, the resulting AS3 declaration looks like this:

{
    "class": "ADC",
    "schemaVersion": "3.11.0",
    "id": "urn:uuid:6ebb5310-dcc6-42ba-83ab-3f9524827bae",
    "label": "Converted Declaration",
    "remark": "Auto-generated by Project acc",
    "Ten": {
        "class": "Tenant",
        "Appl": {
            "class": "Application",
            "template": "http",
            "serviceMain": {
                "layer4": "tcp",
                "pool": "testaccPool",
                "translateServerAddress": true,
                "translateServerPort": true,
                "class": "Service_HTTP",
                "profileTCP": {
                    "bigip": "/Common/tcp"
                },
                "profileHTTP": {
                    "use": "/Common/Shared/testaccHTTP"
                },
                "virtualAddresses": [
                    "192.0.2.14"
                ],
                "virtualPort": 80,
                "snat": "none",
                "remark": "testaccVip"
            },
            "testaccPool": {
                "monitors": [
                    {
                        "use": "/Ten/Appl/testaccMonitor"
                    }
                ],
                "class": "Pool"
            },
            "testaccMonitor": {
                "adaptive": false,
                "interval": 30,
                "dscp": 0,
                "receive": "none",
                "send": "GET /\\r\\n",
                "timeUntilUp": 0,
                "timeout": 91,
                "class": "Monitor",
                "monitorType": "http",
                "targetAddress": "",
                "targetPort": 0
            }
        }
    }
}

Important

Once a conversion has been completed, all files containing sensitive information such as certificates, keys, and passwords, to name a few, should be deleted or moved to a more secure location. Leaving files of these types unsecured can result in exposure and malicious use of the sensitive data.