Barracuda API 3.0 Firmware Barracuda Spam Firewall

Transcription

1 These are instructins t help understand and implement the Barracuda API capability available n the Barracuda Spam Firewall in the versin 3.0 firmware series. This is an extensin f the API released in the versin 2.3 firmware series and cntains many new features and enhancements. If yu have any questins after reading this dcument, please call us at r us at [email protected]. Nte: the API is nly available n certain mdels. Please check with yur sales representative if yu are uncertain whether the mdel yu are cnsidering has the API feature. What is the Barracuda API? The API is a set f six CGI scripts that can be accessed t administer the Barracuda in a remte manner. This is useful fr tasks that happen ften and can be difficult t perfrm neby-ne in the web GUI. An example f ne such task is adding a dmain t the list f allwed dmains n the Barracuda. The API wrks thrugh manipulatin f variables inside f the cnfiguratin. T view the available variables and yur current cnfiguratin, navigate t ADVANCED->Cnfiguratin Backup/Restre in the web GUI. Backup the cnfiguratin file and pen it in any editr that supprts UNIX file frmat (fr instance WrdPad if yu are under Windws). Access t these remte administratin capabilities, is limited t a trusted IP list which can be cnfigured under in BASIC->Administratin in the web GUI in the Allwed SNMP and API Management IP/Range sectin. These scripts are accessible nly t the addresses in that list. The six available scripts are: cnfig_get.cgi: This script is used t return the cntents f a variable. cnfig_set.cgi: This script is used t set the cntents f a variable. cnfig_add.cgi: This script is used t add an entry t a list variable (r add users). cnfig_delete.cgi: This script is used t remve an entry frm a list variable (r delete users). cnfig_search.cgi: This script is used t btain a rw index fr a value in a list variable. cnfig_relad.cgi: This script is used t relad the cnfiguratin This script must be called after making changes with the ther scripts in rder fr yur new settings t be utilized. The rest f this dcument prvides an verview the basic usage f each script, alng with its pssible utput. At the end, a sample sectin is prvided with varius scenaris and sme basic requests t accmplish the desired tasks. Page 1

2 Request/Respnse frm the API Request: These scripts are called just like any ther URL using an HTTP GET. Each API takes its wn set f parameters in the URL that will be detailed in the sectin fr each API belw. T make the request, use the base URL f yur Barracuda that yu use fr cnnecting t the web GUI and append the script yu wish t use. Fr example: Respnse: The respnse frm the scripts is in the frm f XML. The XML utput will appear as fllws fr a successful request r fr a request that has an errr. <?xml versin="1.0" encding="utf-8"?> <cnfig> <scana_blck_level>9</scana_blck_level> </cnfig> <?xml versin="1.0" encding="utf-8"?> <cnfig> <Errr> <Cde>500</Cde> <String>N such variable in cnfiguratin.</string> </Errr> </cnfig> Page 2

3 Using cnfig_get.cgi Variables Allwed: The fllwing variables are utilized by the cnfig_get CGI script. Append these variables t the URL in standard HTTP GET request frmat. variable :: This is a required parameter that tells the API which variable t return. list :: This is an ptinal parameter that tells the API t return a list f variables available n the system. list_users :: This is an ptinal parameter that tells the API t return the current list f user accunts n the system. accunt :: This is an ptinal parameter that tells the API t lkup variable in the specified per-user accunt instead f in the glbal cnfiguratin. Successful Output: If the variable requested is a variable with nly a single value the utput will be different than the utput fr a variable that is a list. The tw types f requests and results are shwn belw. Gets the glbal blck level <?xml versin="1.0" encding="utf-8"?> <cnfig> <scana_blck_level>9</scana_blck_level> </cnfig> Gets the allwed dmain list fr the system <?xml versin="1.0" encding="utf-8"?> <cnfig> <mta_relay_dmain>dmain1.cm</mta_relay_dmain> <mta_relay_dmain>dmain2.cm</mta_relay_dmain> <mta_relay_dmain>dmain3.cm</mta_relay_dmain> <mta_relay_dmain>dmain4.cm</mta_relay_dmain> <mta_relay_dmain>dmain5.cm</mta_relay_dmain> </cnfig> Pssible Errr Cdes: The errr utput frmat is the same as shwn in the Request/Respnse frm the API sectin. The fllwing errr cdes are pssible frm the cnfig_get script. 500 :: N such variable in cnfiguratin. This errr is given if the variable requested is nt present in the glbal cnfiguratin, r the per-user cnfiguratin if an accunt was specified. 501 :: Accunt des nt exist. This errr is given if the accunt requested des nt exist n the system with per-user Page 3

4 Using cnfig_set.cgi Variables Allwed: The fllwing variables are utilized by the cnfig_set CGI script. Append these variables t the URL in standard HTTP GET request frmat. variable :: This is a required parameter that tells the API which variable t return. value :: This is a required parameter that tells the API what value t set fr variable. accunt :: This is an ptinal parameter that tells the API t set variable in the specified per-user accunt instead f in the glbal cnfiguratin. rw :: This is an ptinal parameter that tells the API t set the value fr the given rw inside f variable (Nte: This is nly needed if the variable yu wish t set is a list variable, and is the zer based index f the value t verride). Successful Output: If the variable requested is a list variable, the call must indicate the rw yu wish t manipulate. This rw can be fund by perfrming a cnfig_search API call t request the rw index fr a given value in a list variable. This rw is a zer based index. Samples f bth request types are shwn belw as well as the successful utput. Sets the glbal blck level Sets the last rw in the allwed dmain list frm the cnfig_get example earlier (was dmain5.cm) <?xml versin="1.0" encding="utf-8"?> <cnfig> <Result>200: OK</Result> </cnfig> Pssible Errr Cdes: The errr utput frmat is the same as shwn in the Request/Respnse frm the API sectin. The fllwing errr cdes are pssible frm the cnfig_set script. 800 :: N such variable in cnfiguratin. This errr is given if the variable requested is nt present in the glbal cnfiguratin, r the per-user cnfiguratin if an accunt was specified. 801 :: Accunt des nt exist. This errr is given if the accunt requested des nt exist n the system with per-user 802 :: Variable is a list, s yu must prvide the rw index t alter. This errr is given if a list variable is specified and n rw index t set given. 803 :: Yu must prvide a value t set. This errr is given if n value was specified in the HTTP request. 804 :: This is a custm errr message and will tell yu if the value yu tried t set was nt valid fr the cnfiguratin type (example: trying t set an IP address t a text value). Page 4

5 Using cnfig_add.cgi Variables Allwed: The fllwing variables are utilized by the cnfig_add CGI script. Append these variables t the URL in standard HTTP GET request frmat. variable :: This is a required parameter that tells the API which variable t add t. value :: This is a required parameter that tells the API what value t set fr variable. accunt :: This is an ptinal parameter that tells the API t add t the variable in the specified peruser accunt instead f in the glbal cnfiguratin. variable2 :: This is an ptinal parameter that is used t specify the secnd variable if the main variable is unique acrss tw variables instead f by itself. value2 :: This is an ptinal parameter that tells the API what value t set fr variable2. create :: This is an ptinal parameter that if set tells the API t create the accunt specified if it des nt currently exist n the system. Successful Output: If the variable being manipulated is nt a list variable, the call will fail. If the variable being manipulated is nt unique by itself, then variable2 must be specified. Samples f bth request types, as well as a request t create a user accunt, are shwn belw with the successful utput. Adds anther dmain t the list f allwed dmains Creates the abve user if they dn t already exist (n welcme message is sent yu will need t set the user s passwrd) Adds a new IP range t the list f white-listed IP addresses n the system <?xml versin="1.0" encding="utf-8"?> <cnfig> <Result>200: OK</Result> </cnfig> Pssible Errr Cdes: The errr utput frmat is the same as shwn in the Request/Respnse frm the API sectin. The fllwing errr cdes are pssible frm the cnfig_add script. 700 :: N such variable in cnfiguratin. This errr is given if the variable requested is nt present in the glbal cnfiguratin, r the per-user cnfiguratin if an accunt was specified. 701 :: Accunt des nt exist. This errr is given if the accunt requested des nt exist n the system with per-user 702 :: Value already exists in variable. This errr is given if a value was specified and it is already present in the variable. 703 :: Variable is nt a list. This errr is given if the variable specified is nt a list variable. 704 :: Yu must prvide a value t add. This errr is given if the variable specified des nt have an assciated value. 705 :: Variable is nt the primary key. Page 5

6 This errr is given if the variable specified is nt the primary value but a secndary variable assciated with anther variable. 706 :: Variable is nt unique by itself. 707 :: This errr is given if the variable specified is nt unique alne and needs a secnd variable. This is errr message is returned if the value yu tried t set was nt valid fr the cnfiguratin type (example: trying t set an IP address t a text value). 708 :: Accunt Created This is status message is returned if the accunt was successfully created when yu use cnfig_add t create an accunt. 709 :: Unable t validate accunt. This is errr message is returned if the accunt was unable t be validated thrugh recipient verificatin when the request was submitted. Page 6

7 Using cnfig_delete.cgi Variables Allwed: The fllwing variables are utilized by the cnfig_delete CGI script. Append these variables t the URL in standard HTTP GET request frmat. variable :: This is a required parameter that tells the API which variable t delete frm. value :: This is a required parameter that tells the API what value t delete fr variable. accunt :: This is an ptinal parameter that tells the API t delete frm the variable in the specified per-user accunt instead f in the glbal cnfiguratin. variable2 :: This is an ptinal parameter that is used t specify the secnd variable if the main variable is unique acrss tw variables instead f by itself. value2 :: This is an ptinal parameter that tells the API what value t use fr variable2. remve :: This is an ptinal parameter that if set tells the API t remve the accunt specified if it currently exists n the system. Successful Output: If the variable being manipulated is nt a list variable, the call will fail. If the variable being manipulated is nt unique by itself, then variable2 must be specified. Samples f bth request types, as well as an accunt remval, are shwn belw with the successful utput. Remve a dmain frm the list f allwed dmains Remve a per-user accunt frm the system Remves an IP range frm the list f white-listed IP addresses n the system <?xml versin="1.0" encding="utf-8"?> <cnfig> <Result>200: OK</Result> </cnfig> Pssible Errr Cdes: The errr utput frmat is the same as shwn in the Request/Respnse frm the API sectin. The fllwing errr cdes are pssible frm the cnfig_add script. 600 :: N such variable in cnfiguratin. This errr is given if the variable requested is nt present in the glbal cnfiguratin, r the per-user cnfiguratin if an accunt was specified. 601 :: Accunt des nt exist. This errr is given if the accunt requested des nt exist n the system with per-user 602 :: N such value in variable. This errr is given if a value was specified and it is nt present in the variable. 603 :: Variable is nt a list. This errr is given if the variable specified is nt a list variable. 604 :: Yu must prvide a value t delete. This errr is given if the variable specified des nt have an assciated value. Page 7

8 605 :: Variable is nt the primary key. This errr is given if the variable specified is nt the primary value but a secndary variable assciated with anther variable. 606 :: Variable is nt unique by itself. This errr is given if the variable specified is nt unique alne and needs a secnd variable. 607 :: Accunt remved frm system. This errr is given if the remve ptin caused an accunt t be remved frm the system. Nte: this will remve all settings and quarantine mail fr the given accunt. Page 8

9 Using cnfig_search.cgi Variables Allwed: The fllwing variables are utilized by the cnfig_search CGI script. Append these variables t the URL in standard HTTP GET request frmat. variable :: This is a required parameter that tells the API which variable t lkup. value :: This is a required parameter that tells the API which value t lk fr inside fr the variable. accunt :: This is an ptinal parameter that tells the API t lkup the value fr the variable in the specified per-user accunt instead f in the glbal cnfiguratin. Successful Output: The utput f a successful call is a cln separated value-rw pair inside an XML tag fr the desired variable - results are shwn belw. Gets the index f dmain2.cm frm the earlier cnfig_get example <?xml versin="1.0" encding="utf-8"?> <cnfig> <mta_relay_dmain>dmain2.cm:1</mta_relay_dmain> </cnfig> Pssible Errr Cdes: The errr utput frmat is the same as shwn in the Request/Respnse frm the API sectin. The fllwing errr cdes are pssible frm the cnfig_search script. 900 :: N such variable in cnfiguratin. This errr is given if the variable requested is nt present in the glbal cnfiguratin, r the per-user cnfiguratin if an accunt was specified. 901 :: Accunt des nt exist. This errr is given if the accunt requested des nt exist n the system with per-user 902 :: Variable is nt a list. This errr is given if the variable specified is nt a list variable. 903 :: N such value in variable. This errr is given if a value was specified and it is nt present in the variable. Page 9

10 Using cnfig_relad.cgi Variables Allwed: The fllwing variables are utilized by the cnfig_relad CGI script. Append these variables t the URL in standard HTTP GET request frmat. accunt :: This is an ptinal parameter that tells the API t relad the settings fr the specified peruser accunt instead f the glbal cnfiguratin. Successful Output: The utput f a successful call is a simple 200 OK respnse - results are shwn belw. Relad the settings n the Barracuda and restart any necessary prcesses <?xml versin="1.0" encding="utf-8"?> <cnfig> <Result>200: OK</Result> </cnfig> Pssible Errr Cdes: The errr utput frmat is the same as shwn in the Request/Respnse frm the API sectin. The fllwing errr cdes are pssible frm the cnfig_relad script. 101 :: Accunt des nt exist. This errr is given if the accunt requested des nt exist n the system with per-user Page 10

11 Prblem/Slutin Scenaris fr the API Prblem: Yu need t brwse the list f variables available fr manipulatin. Slutin: The fllwing API call will return a list f variables n the system that yu can manipulate. Call Prblem: Yu need t brwse the list f users currently n the system. Slutin: The fllwing API call will return a list f users currently n the system. Call Prblem: Yur user base needs t be pre-ppulated s that n welcme s are sent t yur users. Slutin: The fllwing steps can be taken t pre-ppulate the users n the system. Fr each user n the system that needs t be created replace NEWUSER with the address f the user and PASSWD with that user s passwrd Call Call Call End Fr Prblem: Yu need t add 5 new dmains and set the destinatin mail server fr each dmain Slutin: The fllwing steps can be taken t add new dmains nt the system. Fr each dmain that needs t be added replace DOMAIN with the new dmain and SERVER with the mail server hst fr that dmain and INDEX with the result f the call t cnfig_search Call Call Call End Fr Call Page 11