SwOS api

SwOS
1

With CSS610 as a new product, any plans for SwOS API ?

1 Like
2

We also want to see a API for SwOS and SwOS lite, and possible telnet/ssh access aswell

3

Actually, SwOS already has an API.
All we need is documentation for it (or reverse engineer it).
To wit:

URL: /link.b

The Authorization header uses a token to keep the session going.

The payload appears to be JSON (with a misleading text/plain MIME-type).
In that JSON payload I can already recognise:
en: Bitmask for all enabled ports. Disabled ports have a zero bit. Ports are numbered little endian style (i.e. bit zero = port 1).
fctc: Bitmask for flow-control TX. Ports are numbered the same as for en.
nm: Port names, normal array, ports are numbered normally.
fctr: Bitmask for flow-control RX. Same bitmask as other fields.
etc.

It’s really easy to reverse engineer (which is a plus).
How about it, Mikrotik, and release the documentation for it?

4

Any plans to document the binary/json API?
It seems that this API is in constant change (or SwOS Lite differs completely from SwOS, API wise).

5

I was inspired. I have built a small docker application to act as a reverse proxy for any number of Mikrotik switches. I then make the call to the switch to pick up their config files “link.b” “sys.b” etc. and return json. I was frustrated that my Homepage dashboard only gave me widgets for RouterOS and not Switch OS.

I’m just testing this at home now and it only picks up Link status, Speed and name for each port but seems to work reliably at least for the two switches I have. I’ll post on here in a wekk or so when I have completed it and where you can pull it from on docker hub. Now would be a good time to request anything specific you need.

Warning, because of my own needs this is brain dead when it comes to security and the router, username and password for the switch are in the url… I’ll look at adding a post option which will hide thouse things.

6

OK I have put this up on Docker Hub and I’m using it with Homepage to give me details of my two switches. https://hub.docker.com/repository/docker/gaileys/mikrotiksw/general

Just do a GET on

/api/v1/getswitch/switchip/switchuser/password

I know that is dreadful, putting the username and password in the URL but the homepage custom api widget doesn’t allow you to control the body of a post so that was the easiest way to do it without having to have a config for each switch.

Happy to modify or add features if people actually want to use it…

7

Thanks @gaileys for your work, but I do not want to run a blackbox on my server/pc and enter username/passwort for my core switch into it. Do you have any git repo, so I can have a look at the source?
I am more interested in understanding the API than a “ready to use” solution. I want to integrate SwitchOS support into my switch manager lib, which already support Cisco, Juniper and other brands.

So, the question remains: Are there any chance to get some documentation on the SwitchOS (Lite) API?

8

I haven’t put this on git but could look to do that. The code is all Scala, and not very good scala at that as it was a quick and dirty solution; so you’d need to be comfortable with that. The easiest way to understand the api is to just use curl:

curl --compressed  --digest -u user:password -v http://192.168.5.2/link.b

The things you need to pull are !sys.b, link.b, stats.b and probably others, depending upon what you want to see, but you will find them all in index.html, together with Javascript to process them.

If you are a Javascript kind of a guy then index.html will tell you everything you need. I’m not so kind of figured out what I needed from clues in the naming conventions used inside the data packages. Most things are hex encoded so you’ll need to parse out the data which is a Javascript object format as close as I can figure. Would have been so much easier if they were json encoded but hey.

I only have two Mikrotik switches to pull data from but most things seem to be comman between them. I don’t run VLANS so none of that was of interest to me and hence I didn’t have examples to reverse engineer…

9

I have partially implemented some stuff to manage my css326 with saltstack. Maybe, this can help to do better things:
https://github.com/y-martin/pkg-python3-mikrotik-swos
https://github.com/y-martin/salt_mikrotik_swos

I don’t have implemented everything (for example I don’t use ACL).

10

Thanks! CSS326 works with SwOS. The API looks straightforward.
But SwOS Lite is a different beast :frowning: Nobody reverse engineered this binary blob yet?

11

Is there also a module for homepage to use with your docker container?
Thanks.

12

@f008600 the difference between SwitchOS and SwitchOS Lite does not seem to be that big.
I recently created a python library and homeassistant integration which currently supports reading PoE stats and during that I noticed, that the biggest difference is the naming of properties and a few properties that are exclusive to one of the two systems.
But the way the content of the properties is encoded is the same in both systems. There are basically a few different types of properties:

  • Bool-list: List of yes/no flags, encoded as a hex-value
  • String: Hex-encoded UTF-8 string
  • Option: Index of a value in the predefined list
  • MAC: MAC-address withtout colons
  • IP: IP-Address as integer with byteorder=little

There are probably more but those are the ones that I needed until now.

What helped me to reverse engineere it was the source code of the webpage. It contains a (obfuscated) description of all endpoints so you can at least see which properties it contains and what they are called in the UI.
Also checking the response before and after a change helps identifying the properties.

1 Like
13

@propro I’ve tried your python lib and it actually worked with my CSS610. Sadly, the lib is kind of bare at the moment, only reading basic information from it. Writing (like VLAN configuration) would be awesome. If I find some time, I will try to implement this.

14

You are right, right now the library only contains basic functionality.
I started implementing it to be able to read power consumption from PoE devices, which I can do now, but I definitly want to extend the library.
My next goal would be to implement changing PoE out status, which means I have to implement write access in the framework. It seems like the MikroTik web app always writes the whole config for an endpoint, even if you only change a single property of a single port. The problem with that is, that you need to know the original value of all properties of an endpoint and send them together with your changes. If a future update brings a new property or renames an old one chances are that a change “destroys” the config.
I haven’t had the time to check that yet tough.
Another problem with writing changes is that the property names between SwOS and SwOS Lite differ and I don’t have a SwOS device to test with. So especially if you really have to write the whole config, it is going to be hard to implement for both systems without having access to both.

15

I see :confused: Writing back values might be a big problem :frowning:

I think there are just two options here to ensure that no furure config will break/accidently deleted:

  1. Fetch and store the whole response, /change/ the desired values within that response and send it back to the device.
  2. Check the version and deny changing values when the version on the device is bigger than the supported version.