We'd love to hear about it! Click here to go to the product suggestion community
I'm trying to automate the HTTPS certificate renewals for a half dozen dev environments using the XG API, and I've figured out how to update a certificate. I also know that I need to make sure that no rule is 'using' the certificate, in order to update it.I've created a self signed certificate that is good for 40 years, which I use temporarily while updating the certificate I need to. My process is three steps.
1 Edit firewall rule to use template certificate.
2 Update 'real' certificate.
3 Edit rule to use 'real' certificate again.
I've got step 2 working with this xml
<Request APIVersion="1702.1"> <Login> <Username>user</Username> <Password>pass</Password> </Login> <Set operation="update"> <Certificate> <Action>UploadCertificate</Action> <Name>Cert_Name</Name> <CertificateFormat>pem</CertificateFormat> <CertificateFile>cert.pem</CertificateFile> <PrivateKeyFile>priv.key</PrivateKeyFile> </Certificate> </Set></Request>
The trouble is, the documentation for XG 17.1/.5 API does not clearly explain what the XML hierarchy is for editing/updating a rule. There is no explanation as to which items are attributes and which items are parameters. There is no indication of case sensitivity, and no explanation of weather 'required' fields are actually required for the update/edit you need to do. In fact, I can't even figure out if my "Set" element needs to have the operation attribute or not, and if so should it be "update" or "edit", or "Edit Firewall Rule". Lets just say, the documentation for the api is near useless.I'm hoping I can find someone that can clearly explain what elements and attributes I need to use to change a rule to use a different certificate.
Here is what I have so far.
<Request APIVersion="1702.1"> <Login> <Username>user</Username> <Password>pass</Password> </Login> <Set operation="Edit"> <SecurityPolicy> <Name>Dev_Http_Rule</Name> <Status>1</Status> <IPFamily>IPv4</IPFamily> <Position>after</Position> <After> <Name>Other_Dev_Http_Rule</Name> </After> <PolicyType>HTTPBased</PolicyType> <HTTPBasedPolicy> <HostedAddress>#Port2</HostedAddress> <HTTPS>1</HTTPS> <RedirectHTTP>1</RedirectHTTP> <ListenPort>443</ListenPort> <HTTPSCertificate>Development_Template_Key</HTTPSCertificate> <Domains> <Domain>d1.com</Domain> <Domain>d2.com</Domain> <Domain>d3.com</Domain> <Domain>d4.com</Domain> </Domains> <AllowFrom> <Address>Any IPv4</Address> </AllowFrom> <AccessPaths>0</AccessPaths> <Exceptions>0</Exceptions> </HTTPBasedPolicy> <Protection>Development Security</Protection> <IntrusionPrevention>dmzpolicy</IntrusionPrevention> <TrafficShapingPolicy>None</TrafficShapingPolicy> <PassHostHeader>1</PassHostHeader> </SecurityPolicy> </Set></Request>
This is the error, with no meaning to me, that I am getting.<Response APIVersion="1702.1" IPS_CAT_VER="1"> <Login> <status>Authentication Successful</status> </Login> <SecurityPolicy transactionid=""> <Status code="501">Configuration parameters validation failed.</Status> <InvalidParams/> </SecurityPolicy></Response>
First of all, you need to touch all elements of an objects, in case you want to update this object.
Best way is to get all the configuration running via GET, put this one into a variable and change the needed information (like certificate). Afterwards POST this value into the XG.
Thats how i would perform such a task.
Simply get all the WAF Rules, change the value, reload the content.
Do not use Edit, try Update.
In reply to LuCar Toni:
Getting the policy first was what I need to have to see the heirarchy. Still a little confusing though. But I got it figured out.
Here is the working XML. Still think SOPHOS should spend a little time making the API Document a little more reader friendly.
<Request APIVersion="1702.1"> <Login> <Username>user</Username> <Password>pass</Password> </Login> <Set operation="update"> <SecurityPolicy transactionid=""> <Name>Dev Rule Name</Name> <IPFamily>IPv4</IPFamily> <Status>Enable</Status> <Position>After</Position> <PolicyType>HTTPBased</PolicyType> <After> <Name>Rule to place after</Name> </After> <HTTPBasedPolicy> <HostedAddress>#Port2</HostedAddress> <HTTPS>Enable</HTTPS> <ListenPort>443</ListenPort> <AccessPaths> <AccessPath> <Path></Path> <allowed_networks>Any IPv4</allowed_networks> <auth_profile/> <backend>Dev webserver</backend> </AccessPath> </AccessPaths> <Exceptions></Exceptions> <ProtocolSecurity>Dev Security</ProtocolSecurity> <CompressionSupport>Disable</CompressionSupport> <RewriteHTML>0</RewriteHTML> <PassHostHeader>Enable</PassHostHeader> <Domains> <Domain>devX.com</Domain>... </Domains> <RewriteCookies>Enable</RewriteCookies> <Certificate>Dev Cert</Certificate> <RedirectHTTP>Enable</RedirectHTTP> </HTTPBasedPolicy> <IntrusionPrevention>dmzpolicy</IntrusionPrevention> <TrafficShapingPolicy>None</TrafficShapingPolicy> </SecurityPolicy> </Set></Request>
In reply to Sire Williamson:
I agree with Sire. Sophos should create proper docs on API.
I strangle sometimes to perform certain tasks through API because a better documentation could help.
Thanks for sharing your work, Sire.
In reply to lferrara:
NP Iferrara. Nothing worse then scowering the dark corners of the internet for answers, and finding that 1 guy that had the same question, but never bothered to follow up on if he found the solution or not. :)
Just to give you a Developer's perspective on this:
The API is used by less than 1% of our customers, possibly less than 0.1%. When doing development when we add something to the UI we also add it to the API and that can take 50% of the dev/test time for how to configure the feature. It is extraordinarily expensive compared to how often it is used. We continue to support it, but I don't think you will see fundamental changes to it especially if that is going to make the development time even higher.
In reply to Michael Dunn:
No offense, but have you looked into WHY people don't use it? It is a pretty powerful feature, but if a company has to assign 100 man hours to learning the syntax because the documentation is so confusing, they are obviously going to look at other ways of accomplishing what they need to. Automating certificate renewals is a pretty common need, even if you have as little as 20 certificates to manage.Cisco has a very verbose scripting language, but they also have good documentation available. I couldn't even give a number to the amount of network admins that use scripting to manage their workload. APIs make that very convenient.
So while I understand the need to justify the man hours to develop the documentation, you should include a CBA on how many more customers would use the API if it was easier to pick up and work with, and how many potential higher level customers would consider the XG if their Admins saw it as a robust alternative to Cisco.
It is hard to teach people API, if they are not familiar with Scripting in general.
As for now, it is XML based and it is kinda straight forward. I can actually code this without Docs.
Because basically i "click" my object in Webadmin.
Export the configuration made in Webadmin via "Import /export" in Administration and getting the EXACT thing, i need to push to the XG.
So you want to configure 500 Firewall rules?
Create one Rule, export it via function, looking into the syntax of this XML File.
Edit the XML File, add the 499 Rules into the XML File via Script and pushing this File to the API.
Depending how good you are with Python, Powershell, bash etc.
I am not saying, it is good, but for people with Scripting knowledge, you can actually quite easily figure out what to do.
But as michael said, most people are not doing it at all. They are not using scripting, who knows why.
The reason why is probably as much related to the typical customer size. I agree that higher level customers who are comparing us to Cisco may care about API and documentation. Lower level customers will not. The auto-documentation that creates APIDocument.zip is what it is. Support/help documentation teams probably look at the number of incoming customer contacts and build out new KBs etc based on the volume of issues.
Have you seen this video: https://www.youtube.com/watch?v=VN_uqQpuBG0
Thanks for the link share. Had no seen that video, but that is because I prefer to read than watch the video. I find it easier to skip around to what I need in text than in a video. That is just my preference though, I'm in no way saying it is everyone's.
We just switched from Cisco to SOPHOS, (for a number of reasons) so I was under a time crunch, and I was just frustrated that I couldn't quickly find a way of doing what I needed to. Overall we are happy with the product, it just would have made things smoother had a bit more info been in the API docs.
I think there is three stages:
1) How do I configure / get anything to work
2) Its working (Hello World), now what approach do I use to determine what to do
3) How do I use this specific object
I suspect we are ok at documenting 1 and 3, but not 2. For example, anything that you GET you should be able to take that object and immediately SET it. If the name does not change then you are doing an update, if the name changes then it is a new object. So if you want to figure out how to SET something you should GET an example and use that as your basis, only referring to the documentation if you are having trouble changing a specific parameter. But that approach is hard to write in a Help file.
I did also find this KB, which might be useful.
Looking on the forums, I can see that there have been a few posts about API and certificates, I think that is one of the more common use cases. And it can be complex due to the file upload. I will ask the KB team if there is anything they can do to help document that specific use case.