Barracuda Spam Firewall Guide

Barracuda API – 3.x Firmware

Barracuda Spam Firewall

These are instructions to help understand and implement the Barracuda API capability available on the Barracuda
Spam Firewall in the version 3.x firmware series. If you have any questions after reading this document, please
call us at 408-342-5400 or email us at [e-mail]. Note: the API is only available on certain
models. Please check with your sales representative if you are uncertain whether the model you are considering
has the API feature.

What is the Barracuda API?

The Barracuda Spam Firewall APIs are a set of CGI scripts that can be used to administer the Barracuda
Spam Firewall in a remote manner. This is useful for tasks that happen frequently but may be difficult to
perform one-by-one in the Web UI. An example of one such task is adding a domain to the list of allowed
domains on the Barracuda Spam Firewall.

The API works through manipulation of variables inside of the configuration. To view the available variables in
your current configuration, create a system configuration backup file, and view the contents in any editor that
supports UNIX file format (for instance, NotePad if you are under Windows).

Access to these remote administration capabilities is limited to IPs on a trusted IP list configured on the
BASIC->Administration page, in the “Allowed SNMP and API Management IP/Range” section. Attempts to call
these APIs from any IP address that is not on that list will be denied.

The following API scripts are available:

● config_get.cgi: This script is used to return the contents of a variable.

● config_set.cgi: This script is used to set the contents of a variable.

● config_set_bulk.cgi: This script is used to set the contents of a multiple variables (available on

firmware version 3.4 and higher).

● config_add.cgi: This script is used to add an entry to a list variable (or add users).

● config_delete.cgi: This script is used to remove an entry from a list variable (or delete users).

● config_search.cgi: This script is used to obtain a row index for a value in a list variable.

● config_reload.cgi: This script is used to reload the configuration settings. This script must be called

after making changes with the other scripts in order for your new settings to be utilized.

● add_domain.cgi: This script is used to add additional domains. (available on firmware version 3.5

and higher).

● delete_domain.cgi: This script is used to remove existing domains. (available on firmware version

3.5 and higher).

This document provides an overview of the basic usage of each script, along with possible output. Various
scenarios and some basic requests on how to accomplish the desired tasks are provided in the final section.

Note: Use of config_search.cgi and the associated calls that use a row number to alter domains has been
deprecated. That functionality has been replaced as of the 3.4.11 firmware by new API scripts that deal
directly with domains: add_domain.cgi, and delete_domain.cgi. Additionally, the original scripts have been
modified as well to use a 'domain' parameter instead of a row parameter to change domain values. The ability
to use the 'row' parameter to change domain values will soon be removed completely.

Revision 2a - 070611 Page 1

Barracuda API – 3.x Firmware

Barracuda Spam Firewall

Request/Response from the API

Request: These scripts are called just like any other URL using an HTTP GET (or an HTTP POST for

config_set_bulk.cgi). Each API takes its own set of parameters in the URL that will be detailed in the section
for each API below. To make the request, use the base URL of your Barracuda that you use for connecting to
the Web UI and append the script you wish to use. For example: http://barracuda.mydomain.com:8000/cgi-

bin/config_get.cgi

Response: The response from the scripts is in the form of XML. The XML output will appear as follows for a
successful request or for a request that has an error.

<?xml version="1.0" encoding="UTF-8" ?>
<config>

<scana_block_level>9</scana_block_level>

</config>

<?xml version="1.0" encoding="UTF-8" ?>
<config>

<Error>

<Code>500</Code>
<String>No such variable in configuration.</String>

</Error>

</config>

Revision 2a - 070611 Page 2

Barracuda API – 3.x Firmware

Barracuda Spam Firewall

Using config_get.cgi

Variables Allowed: The following variables are utilized by the config_get CGI script. Append these variables

to the URL in standard HTTP GET request format.

● variable :: This is a required parameter that tells the API which variable to return.

● password :: This is a required parameter for the usage of the API. The API password is used to

authenticate access to a page, and is set by your administrator.

● row :: This is an optional parameter that tells the API to get the value for the given row inside of

variable. (Note: This is only available if the variable you wish to get is a list variable, and is the zero

based index of the value to retrieve).

● list :: This is an optional parameter that tells the API to return a list of variables available on the

system.

● list_users :: This is an optional parameter that tells the API to return the current list of user accounts

on the system.

● account :: This is an optional parameter that tells the API to lookup variable in the specified per-user

account instead of in the global configuration.

● domain :: This is an optional parameter used to retrieve a variable's value from a specific domain.

(available on firmware version 3.5 and higher).

Successful Output: If the variable requested is a variable with only a single value the output will be different
than the output for a variable that is a list. The two types of requests and results are shown below.

http://barracuda/cgi-bin/config_get.cgi?variable=scana_block_level&password=api_passsword

Gets the global block level

<?xml version="1.0" encoding="UTF-8" ?>
<config>

<scana_block_level>9</scana_block_level>

</config>

http://barracuda/cgi-bin/config_get.cgi?variable=scana_pd_block_level&domain=foo.com&password=api_password

Gets the block level for domain foo.com

<?xml version="1.0" encoding="UTF-8" ?>
<config>

<scana_pd_block_level>9</scana_pd_block_level>

</config>

http://barracuda/cgi-bin/config_get.cgi?variable=mta_relay_domain&password=api_password

Gets the allowed domain list for the system

<?xml version="1.0" encoding="UTF-8" ?>

<config>

<mta_relay_domain>domain1.com</mta_relay_domain>
<mta_relay_domain>domain2.com</mta_relay_domain>
<mta_relay_domain>domain3.com</mta_relay_domain>

</config>

Revision 2a - 070611 Page 3

Barracuda API – 3.x Firmware

Barracuda Spam Firewall

Possible Error Codes: The error output format is the same as shown in the Request/Response from the
API section. The following error codes are possible from the config_get script.

• 500 :: No such variable in configuration.

o This error is given if the variable requested is not present in the global configuration, or the

per-user configuration if an account was specified.

• 501 :: Account does not exist.

o This error is given if the account requested does not exist on the system with per-user

settings.

• 502 :: Row does not exist.

o This error is given if the requested row does not exist in the requested variable.

Revision 2a - 070611 Page 4

Barracuda API – 3.x Firmware

Barracuda Spam Firewall

Using config_set.cgi

Variables Allowed: The following variables are utilized by the config_set CGI script. Append these variables

to the URL in standard HTTP GET request format.

● variable :: This is a required parameter that tells the API which variable to return.

● value :: This is a required parameter that tells the API what value to set for variable.

● password :: This is a required parameter for the usage of the API. The API password is used to

authenticate access to a page, and is set by your administrator.

● account :: This is an optional parameter that tells the API to set variable in the specified per-user

account instead of in the global configuration.

● row :: This is an optional parameter that tells the API to set the value for the given row inside of

variable. (Note: This is only needed if the variable you wish to set is a list variable, and is the zero

based index of the value to override).

● domain :: This is an optional parameter used to set a variable's value for a specific domain.

(available on firmware version 3.5 and higher).

Successful Output: If the variable requested is a list variable, the call must indicate the row you wish to
manipulate. This row can be found by performing a config_search API call to request the row index for a
given value in a list variable. This row is a zero-based index. Samples of both request types are shown below
as well as the successful output.

http://barracuda/cgi-bin/config_get.cgi?variable=scana_block_level&value=4&password=api_password

Sets the global block level

http://barracuda/cgi-bin/config_set.cgi?variable=scana_pd_tag_level&value=7&domain=foo.com&pasword=api_password

Sets the per-domain tag level to the value 7 for foo.com.

<?xml version="1.0" encoding="UTF-8" ?>
<config>

<Result>200: OK</Result>

</config>

Possible Error Codes: The error output format is the same as shown in the Request/Response from the
API section. The following error codes are possible from the config_set script.

• 800 :: No such variable in configuration.

o This error is given if the variable requested is not present in the global configuration, or the

per-user configuration if an account was specified.

• 801 :: Account does not exist.

o This error is given if the account requested does not exist on the system with per-user

settings.

• 802 :: Variable is a list, so you must provide the row index to alter.

o This error is given if a list variable is specified and no row index to set given.

• 803 :: You must provide a value to set.

o This error is given if no value was specified in the HTTP request.

• 804 :: Variable-specific error message.

o This is a custom error message and will tell you if the value you tried to set was not valid for

the configuration type (example: trying to set an IP address to a text value).

Revision 2a - 070611 Page 5

Barracuda API – 3.x Firmware

Barracuda Spam Firewall

Using config_set_bulk.cgi

Variable and value format: There are three distinct ways to set the value of variables: one to set a single

value for a variable, one to set a single row for a list variable, and one to set all values for a list variable.

● variable=value :: This sets the variable variable to value value.

● variable:row=value :: This sets the list variable variable to the value value at row index row.

● variable=value :: This sets the list variable variable to all values specified by the string value, where

each row's value is separated by a literal \n (backslash n), or by the newline character. The API will
then automatically set each row value appropriately.

Variables Allowed: The following variables are utilized by the config_set_bulk CGI script. These variables
should be provided as part of the HTTP POST request.

● password :: This is a required parameter for the usage of the API. The API password is used to

authenticate access to a page, and is set by your administrator.

● account :: This is an optional parameter that tells the API to set variables in the specified per-user

account instead of in the global configuration.

● force :: This is an optional parameter that tells the API to set the values for the given variables in a

non-atomic fashion. This will cause the API to set the variables it can, and return errors for the
variables it cannot.

● domain :: This is an optional parameter used to set a variable's value for a specific domain. (available

on firmware version 3.5 and higher).

Successful Output: Samples of all three request types are shown below as well as the successful output.

http://barracuda/cgi-bin/config_set_bulk.cgi?scana_block_level=4&scana_tag_level=5&password=api_password

Sets the global block level, and the global tag level.

http://barracuda/cgi-

bin/config_set_bulk.cgi?scana_pd_tag_level=5&scana_pd_block_level=6&domain=foo.com&password=api_password

Sets the per-domain tag level and the per-domain block level for the domain foo.com.

<?xml version="1.0" encoding="UTF-8" ?>
<config>

<Result>200: OK</Result>

</config>

Possible Error Codes: The error output format is the same as shown in the Request/Response from the
API section. The following error codes are possible from the config_set_bulk script.

• 800 :: No such variable in configuration.

o This error is given if the variable requested is not present in the global configuration, or the

per-user configuration if an account was specified.

• 801 :: Account does not exist.

o This error is given if the account requested does not exist on the system with per-user

settings.

• 803 :: You must provide a value to set.

o This error is given if no value was specified in the HTTP request.

• 804 :: Variable-specific error message.

o This is a custom error message and will tell you if the value you tried to set was not valid for

the configuration type (example: trying to set an IP address to a text value).

Revision 2a - 070611 Page 6

Barracuda API – 3.x Firmware

Barracuda Spam Firewall

Using config_add.cgi

Variables Allowed: The following variables are utilized by the config_add CGI script. Append these variables

to the URL in standard HTTP GET request format.

● variable :: This is a required parameter that tells the API which variable to add to.

● value :: This is a required parameter that tells the API what value to set for variable.

● password :: This is a required parameter for the usage of the API. The API password is used to

authenticate access to a page, and is set by your administrator.

● account :: This is an optional parameter that tells the API to add to the variable in the specified per-

user account instead of in the global configuration.

● variable2 :: This is an optional parameter that is used to specify the second variable if the main

variable is unique across two variables instead of by itself.

● value2 :: This is an optional parameter that tells the API what value to set for variable2.

● create :: This is an optional parameter that if set tells the API to create the account specified if it does

not currently exist on the system.

Successful Output: If the variable being manipulated is not a list variable, the call will fail. If the variable
being manipulated is not unique by itself, then variable2 must be specified. Samples of both request types, as
well as a request to create a user account, are shown below with the successful output.

http://barracuda/cgi-bin/config_add.cgi?account=[e-mail]&create=1&password=api_password

Creates the above user if they don’t already exist (no welcome message is sent – you will need to set the user’s password)

http://barracuda/cgi­bin/config_add.cgi?variable=mta_trusted_relay_address&value=1.1.1.1&variable2=mta_trusted_relay_netmask&value2=255.0.0.0
&password=api_password

Adds a new IP range to the list of white-listed IP addresses on the system

<?xml version="1.0" encoding="UTF-8" ?>

<config>

<Result>200: OK</Result>

</config>

Possible Error Codes: The error output format is the same as shown in the Request/Response from the
API section. The following error codes are possible from the config_add script.

• 700 :: No such variable in configuration.

o This error is given if the variable requested is not present in the global configuration, or the

per-user configuration if an account was specified.

• 701 :: Account does not exist.

o This error is given if the account requested does not exist on the system with per-user

settings.

• 702 :: Value already exists in variable.

o This error is given if a value was specified and it is already present in the variable.

• 703 :: Variable is not a list.

o This error is given if the variable specified is not a list variable.

• 704 :: You must provide a value to add.

o This error is given if the variable specified does not have an associated value.

Revision 2a - 070611 Page 7

• 705 :: Variable is not the primary key.

o This error is given if the variable specified is not the primary value but a secondary variable

associated with another variable.

• 706 :: Variable is not unique by itself.

o This error is given if the variable specified is not unique alone and needs a second variable.

• 707 :: Variable-specific error message.

o This is error message is returned if the value you tried to set was not valid for the

configuration type (example: trying to set an IP address to a text value).

• 708 :: Account Created

o This is status message is returned if the account was successfully created when you use

config_add to create an account.

• 709 :: Unable to validate account.

o This is error message is returned if the account was unable to be validated through recipient

verification when the request was submitted.

Barracuda API – 3.x Firmware

Barracuda Spam Firewall

Revision 2a - 070611 Page 8

Barracuda API – 3.x Firmware

Barracuda Spam Firewall

Using config_delete.cgi

Variables Allowed: The following variables are utilized by the config_delete CGI script. Append these

variables to the URL in standard HTTP GET request format.

● variable :: This is a required parameter that tells the API which variable to delete from.

● value :: This is a required parameter that tells the API what value to delete for variable.

● password :: This is a required parameter for the usage of the API. The API password is used to

authenticate access to a page, and is set by your administrator.

● account :: This is an optional parameter that tells the API to delete from the variable in the specified

per-user account instead of in the global configuration.

● variable2 :: This is an optional parameter that is used to specify the second variable if the main

variable is unique across two variables instead of by itself.

● value2 :: This is an optional parameter that tells the API what value to use for variable2.

● remove :: This is an optional parameter that, if set, tells the API to remove the account specified if it

currently exists on the system.

Successful Output: If the variable being manipulated is not a list variable, the call will fail. If the variable
being manipulated is not unique by itself, then variable2 must be specified. Samples of both request types, as
well as an account removal, are shown below with the successful output.

http://barracuda/cgi-bin/config_delete.cgi?account=[e-mail]&remove=1&password=api_password

Remove a per-user account from the system

http://barracuda/cgi­bin/config_delete.cgi?variable=mta_trusted_relay_address&value=1.1.1.1&variable2=mta_trusted_relay_netmask&value2=255.0.

0.0&password=api_password

Removes an IP range from the list of white-listed IP addresses on the system

<?xml version="1.0" encoding="UTF-8" ?>

<config>

<Result>200: OK</Result>

</config>

Possible Error Codes: The error output format is the same as shown in the Request/Response from the
API section. The following error codes are possible from the config_add script.

• 600 :: No such variable in configuration.

o This error is given if the variable requested is not present in the global configuration, or the

per-user configuration if an account was specified.

• 601 :: Account does not exist.

o This error is given if the account requested does not exist on the system with per-user

settings.

• 602 :: No such value in variable.

o This error is given if a value was specified and it is not present in the variable.

• 603 :: Variable is not a list.

o This error is given if the variable specified is not a list variable.

• 604 :: You must provide a value to delete.

o This error is given if the variable specified does not have an associated value.

Revision 2a - 070611 Page 9

• 605 :: Variable is not the primary key.

o This error is given if the variable specified is not the primary value but a secondary variable

associated with another variable.

• 606 :: Variable is not unique by itself.

o This error is given if the variable specified is not unique alone and needs a second variable.

• 607 :: Account removed from system.

o This error is given if the remove option caused an account to be removed from the system.

Note: this will remove all settings and quarantine mail for the given account.

Barracuda API – 3.x Firmware

Barracuda Spam Firewall

Revision 2a - 070611 Page 10

Barracuda API – 3.x Firmware

Barracuda Spam Firewall

Using config_search.cgi

Variables Allowed: The following variables are utilized by the config_search CGI script. Append these

variables to the URL in standard HTTP GET request format.

● variable :: This is a required parameter that tells the API which variable to look up.

● value :: This is a required parameter that tells the API which value to look for inside for the variable.

● password :: This is a required parameter for the usage of the API. The API password is used to

authenticate access to a page, and is set by your administrator.

● account :: This is an optional parameter that tells the API to look up the value for the variable in the

specified per-user account instead of in the global configuration.

Note: This should no longer be used to obtain row indexes to modify domains. That functionality is currently
deprecated, and will be removed from future versions of the firmware.

Successful Output: The output of a successful call is a colon-separated value-row pair inside an XML tag for
the desired variable.

http://barracuda/cgi-bin/config_search.cgi?variable=mta_trusted_relay_address&value=1.1.1.1&password=api_password

Gets the index of 1.1.1.1 from the variable mta_trusted_relay_address.

<?xml version="1.0" encoding="UTF-8" ?>

<config>

<mta_trusted_relay_address>1.1.1.1:1</mta_trusted_relay_address>

</config>

Possible Error Codes: The error output format is the same as shown in the Request/Response from the
API section. The following error codes are possible from the config_search script.

• 900 :: No such variable in configuration.

o This error is given if the variable requested is not present in the global configuration, or the

per-user configuration if an account was specified.

• 901 :: Account does not exist.

o This error is given if the account requested does not exist on the system with per-user

settings.

• 902 :: Variable is not a list.

o This error is given if the variable specified is not a list variable.

• 903 :: No such value in variable.

o This error is given if a value was specified and it is not present in the variable.

Revision 2a - 070611 Page 11

Barracuda API – 3.x Firmware

Barracuda Spam Firewall

Using config_reload.cgi

Variables Allowed: The following variables are utilized by the config_reload CGI script. Append these

variables to the URL in standard HTTP GET request format.

● password :: This is a required parameter for the usage of the API. The API password is used to

authenticate access to a page, and is set by your administrator.

● account :: This is an optional parameter that tells the API to reload the settings for the specified per-

user account instead of the global configuration.

Successful Output: The output of a successful call is a simple 200 OK response - results are shown below.

http://barracuda/cgi-bin/config_reload.cgi?password=api_password

Reload the settings on the Barracuda and restart any necessary processes

<?xml version="1.0" encoding="UTF-8" ?>

<config>

<Result>200: OK</Result>

</config>

Possible Error Codes: The error output format is the same as shown in the Request/Response from the
API section. The following error codes are possible from the config_reload script.

• 101 :: Account does not exist.

o This error is given if the account requested does not exist on the system with per-user

settings.

Revision 2a - 070611 Page 12

Barracuda API – 3.x Firmware

Barracuda Spam Firewall

Using add_domain.cgi

Variables Allowed: The following variables are utilized by the add_domain CGI script. Append these

variables to the URL in standard HTTP GET request format.

● domain :: This required parameter is the name of the domain being added.

● password :: This is a required parameter for the usage of the API. The API password is used to

authenticate access to a page, and is set by your administrator.

Successful Output: If the provided domain already exists, then the call will fail. The output of a successful
call is a simple 200 OK response, and is shown below.

http://barracuda/cgi-bin/add_domain.cgi?domain=foo.com&password=api_password

Add an additional domain called foo.com.

<?xml version="1.0" encoding="UTF-8" ?>

<config>

<Result>200: OK</Result>

</config>

Possible Error Codes: The error output format is the same as shown in the Request/Response from the
API section. The following error codes are possible from the add_domain script.

• 401 :: Your machine does not have access rights to administer configurations.

o This error is given if the originating request accessing the API does not have administration

privileges.

• 406 :: Incorrect parameters for API call.

o This error is given if not all required parameters are given for the API request.

• 500 :: An unknown error has occurred.

o This error is given if the API is currently experiencing an unknown failure.

IMPORTANT: The above error codes are valid only for the initial versions of the 3.5 firmware, and are subject
to change. Any changes to the error codes will be noted in the Release Notes for the firmware version in
which they occur.

Revision 2a - 070611 Page 13

Barracuda API – 3.x Firmware

Barracuda Spam Firewall

Using delete_domain.cgi

Variables Allowed: The following variables are utilized by the remove_domain CGI script. Append these

variables to the URL in standard HTTP GET request format.

● domain :: This required parameter is the name of the domain being removed.

● password :: This is a required parameter for the usage of the API. The API password is used to

authenticate access to a page, and is set by your administrator.

Successful Output: If the domain name provided in the domain parameter does not exist, then the call will
fail. The output of a successful call is a simple 200 OK response, and is shown below:

http://barracuda/cgi-bin/remove_domain.cgi?domain=foo.com&password=api_password

Removes a domain called foo.com.

<?xml version="1.0" encoding="UTF-8" ?>

<config>

<Result>200: OK</Result>

</config>

Possible Error Codes: The error output format is the same as shown in the Request/Response from the
API section. The following error codes are possible from the remove_domain script.

• 401 :: Your machine does not have access rights to administer configurations.

o This error is given if the originating request accessing the API does not have administration

privileges.

• 406 :: Incorrect parameters for API call.

o This error is given if not all required parameters are given for the API request.

• 500 :: An unknown error has occurred.

o This error is given if the API is currently experiencing an unknown failure.

IMPORTANT: The above error codes are valid only for the initial versions of the 3.5 firmware, and are subject
to change. Any changes to the error codes will be noted in the Release Notes for the firmware version in
which they occur.

Revision 2a - 070611 Page 14

Barracuda API – 3.x Firmware

Barracuda Spam Firewall

Problem/Solution Scenarios for the API

Problem: You need to browse the list of variables available for manipulation.

Solution: The following API call will return a list of variables on the system that you can manipulate.

Call http://barracuda/cgi-bin/config_get.cgi?list=1

Problem: You need to browse the list of users currently on the system.

Solution: The following API call will return a list of users currently on the system.

Call http://barracuda/cgi-bin/config_get.cgi?list_users=1

Problem: Your user base needs to be pre-populated so that no welcome emails are sent to your users.

Solution: The following steps can be taken to pre-populate the users on the system.

For each user on the system that needs to be created replace NEWUSER with the email address of

the user and PASSWD with that user’s password

Call http://barracuda/cgi-bin/config_add.cgi?create=1&account=NEWUSER
Call http://barracuda/cgi-bin/config_set.cgi?account=NEWUSER&variable=user_password&value=PASSWD
Call http://barracuda/cgi-bin/config_reload.cgi?account=NEWUSER

End For

Problem: You need to add 5 new domains and set the destination mail server for each domain

Solution: The following steps can be taken to add new domains onto the system.

For each domain that needs to be added replace DOMAIN with the new domain and SERVER with

the mail server host for that domain and INDEX with the result of the call to config_search

Call http://barracuda/cgi-bin/add_domain.cgi?domain=DOMAIN
Call http://barracuda/cgi-bin/config_set.cgi?variable=mta_relay_advanced_host&domain=DOMAIN&value=SERVER

End For

Call http://barracuda/cgi-bin/config_reload.cgi

Revision 2a - 070611 Page 15