Skip to content

Instantly share code, notes, and snippets.

@morteza-mori

morteza-mori/ibsng_api_intro.md

Forked from mxamin/ibsng_api_intro.md
Created October 29, 2017 06:50
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save morteza-mori/ceb738ddf211b3a42dd7f0e4a01982e3 to your computer and use it in GitHub Desktop.
Save morteza-mori/ceb738ddf211b3a42dd7f0e4a01982e3 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
ibsng_api_intro.md

Introduction

The following document describes how we can communicate with IBSng API through JSONRPC.

Note that IBSng is capable of handling requests in XML format as well, which in this case the IBSng XMLRPC server is responsible of processing/answering the requests but it is not the purpose of this document

All the samples of this document are implemented with curl command to make it independent of any programming languages.

Each operation in IBSng can be done by calling its appropriate method. The methods are categorized in different sections called handler. All the handlers/methods are described in here. So if we want to refer to an specific method it has following form: <handler_name>.<method_name>.

For example if you decide to send the login request, you must find its handler and of course its method. In this case both of handler and method have the same name login, so in your request you must refer to it by method="login.login".

The default port of IBSng JSONRPC server is 1237. In following samples we already have an installed IBSng on a system with IP address 192.168.1.4 with port 1237 open which JSONRPC server is listening on. Also we have provided with a username: system, password: sys which has the required permission. We are sending our requests from IP address: 192.168.1.101.

Authentication

Before we decide to send any request to IBSng, first we must authenticate ourself, this can be done by calling the login.login method of IBSng:

$ curl -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -H "Accept-Charset: utf-8" \
       -H "Cache-Control: no-cache" \
       -X POST \
       -d '{"params": {"auth_remoteaddr": "192.168.1.101", "auth_type": "ANONYMOUS", "auth_name": "ANONYMOUS", "auth_pass": "ANONYMOUS", "login_auth_name": "system", "login_auth_pass": "sys", "create_session": true, "login_auth_type": "ADMIN"}, "method": "login.login"}' \
       http://192.168.1.104:1237/

Output:

{"id": null, "result": "xe1v3t6q727c", "error": null}

As you can see in response IBSng provided us with a session id: xe1v3t6q727c (the value in result field) which you must include in from now on in every request you send, otherwise you're request will be rejected.

All responses have only three fields: id, result and error.

If an error occurs in processing the request, IBSng will tell us what/where the error is by filling out the error field. null value means NO error.

If you're authenticating as a simple user you must change the login_auth_type to NORMAL_USER. For more information look at the handlers document.

Create New Group

We can create a new group by calling the group.addNewGroup method. Each group must be assigned to an existing ISP (the ISP which owns the group). In following example we assume that such ISP with the name my_isp is created before and we want to create a new group with the name my_group:

$ curl -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -H "Accept-Charset: utf-8" \
       -H "Cache-Control: no-cache" \
       -X POST \
       -d '{"params": {"auth_remoteaddr": "192.168.1.101", "auth_type": "ADMIN", "auth_name": "system", "auth_session": "xe1v3t6q727c", "group_name": "my_group", "status": "ACTIVE", "isp_name": "my_isp", "comment": ""}, "method": "group.addNewGroup"}' \
       http://192.168.1.104:1237/

Output:

{"id": null, "result": 13, "error": null}

The value of result field is ID of created group which in this case is 13.

Create New User

We can create a new user by calling the user.addNewUsers method. By calling this method we have to provide following parameters:

  • count: how many users you want to create
  • isp_name: the isp which new user(s) belong to
  • group_name: which group new user(s) belong to
  • credit: initial credit of new user(s)
  • credit_comment: short description about the initial credit we assigned to new user(s)

For the following example we assume that we have already created an ISP named my_isp and a group named my_group. We want to create only ONE user with initial credit of 1500 units. We leave the credit comment empty:

$ curl -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -H "Accept-Charset: utf-8" \
       -H "Cache-Control: no-cache" \
       -X POST \
       -d '{"params": {"auth_remoteaddr": "192.168.1.101", "auth_type": "ADMIN", "auth_name": "system", "auth_session": "xe1v3t6q727c", "count": 1, "isp_name": "my_isp", "group_name": "my_group", "credit": 1500, "credit_comment": ""}, "method": "user.addNewUsers"}' \
       http://192.168.1.104:1237/

Output:

{"id": null, "result": [59], "error": null}

As you can see in response message, IBSng created only one user with user ID of 59 (look at value of result field).

you may have noticed that the created user has no username/password for authentication purposes, if we decide to set this parameter we have to call another method named user.updateUserAttrs and assigning new values to normal_username and normal_password attributes.

(Un)Lock a User

Locking mode is an attribute of a user named lock, so to lock an existing user we have to call user.updateUserAttrs method and set this attribute as follow:

$ curl -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -H "Accept-Charset: utf-8" \
       -H "Cache-Control: no-cache" \
       -X POST \
       -d '{"params": {"auth_remoteaddr": "192.168.1.101", "auth_type": "ADMIN", "auth_name": "system", "auth_session": "xe1v3t6q727c", "user_id": "59", "attrs": {"lock": "my lock"}, "to_del_attrs": []}, "method": "user.updateUserAttrs"}' \
       http://192.168.1.104:1237/

Output:

{"id": null, "result": "", "error": null}

In response you will receive nothing which is a good sign that your request executed successfully (of course you must check that the value of error field is null).

As you can see we passed the value of user_id as a string, because IBSng is capable of updating attributes of multiple users in one request, all you have to do is passing the ID of users you want to update their attributes as a string separated by ,.

The text we assigned to lock attribute ('my lock') will be saved as lock reason in IBSng.

If you want to completely delete an existing attribute, you can pass it to to_del_attrs field. Since type of this field is a list you can delete multiple attributes in one request as well.

To unlock a locked user all you have to do is to delete the lock attribute:

$ curl -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -H "Accept-Charset: utf-8" \
       -H "Cache-Control: no-cache" \
       -X POST \
       -d '{"params": {"auth_remoteaddr": "192.168.1.101", "auth_type": "ADMIN", "auth_name": "system", "auth_session": "xe1v3t6q727c", "user_id": "59", "attrs": {}, "to_del_attrs": ["lock"]}, "method": "user.updateUserAttrs"}' \
       http://192.168.1.104:1237/

Output:

{"id": null, "result": "", "error": null}

Again we got an empty message in response which is a good sign.

Kill/Clear User

To kill/clear a user we have to call user.killUserByID method. This method has following parameters:

  • user_id: ID of the user we want to kill/clear
  • kill: if true user will be killed, otherwise user will be cleared

For difference between killing and clearing an online user refer to IBSng wiki page at http://wiki.parspooyesh.com.

$ curl -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -H "Accept-Charset: utf-8" \
       -H "Cache-Control: no-cache" \
       -X POST \
       -d '{"params": {"auth_remoteaddr": "192.168.1.101", "auth_type": "ADMIN", "auth_name": "system", "auth_session": "xe1v3t6q727c", "user_id": 59, "kill": true}, "method": "user.killUserByID"}' \
       http://192.168.1.104:1237/

Output:

{"id": null, "result": "", "error": null}

Again empty message means the request executed successfully.

Create New Charge

To create a new charge we have to call charge.addNewCharge method. This method has following parameters:

  • charge_name: name of new charge we want to create
  • isp_name: name of ISP which this charge belongs to
  • comment: a short description about this new charge

In following example we are going to create a new charge named my_charge which belongs to an ISP named my_isp. We leave the comment field empty:

$ curl -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -H "Accept-Charset: utf-8" \
       -H "Cache-Control: no-cache" \
       -X POST \
       -d '{"params": {"auth_remoteaddr": "192.168.1.101", "auth_type": "ADMIN", "auth_name": "system", "auth_session": "xe1v3t6q727c", "charge_name": "my_charge", "isp_name": "my_isp", "comment": ""}, "method": "charge.addNewCharge"}' \
       http://192.168.1.104:1237/

Output:

{"id": null, "result": 5, "error": null}

The new charge created with ID of 5.

When you create a new charge it will be created along a new charge rule with the same name, assigned to our new charge. Of course we can create new charge rules as well. To see the difference between charge and charge rule look at IBSng wiki page: http://wiki.parspooyesh.com

Delete an Existing User

We can delete an existing user by calling user.delUser method. This method has following parameters:

  • user_id: ID of user(s) we want to delete as a string separated by ,
  • delete_comment: short description about why we are going to delete specified user(s)
  • del_connection_logs: if true we will delete all users' connection log records as well
  • del_audit_logs: if true we will delete all users' audit log records as well

You can find out what connection/audit logs are by looking at IBSng wiki page at http://wiki.parspooyesh.com.

In following example we are going to delete a user with ID 59 with all its connection/audit logs. We leave the delete comment empty:

$ curl -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -H "Accept-Charset: utf-8" \
       -H "Cache-Control: no-cache" \
       -X POST \
       -d '{"params": {"auth_remoteaddr": "192.168.1.101", "auth_type": "ADMIN", "auth_name": "system", "auth_session": "xe1v3t6q727c", "user_id": "59", "del_connection_logs": true, "del_audit_logs": true, "delete_comment": ""}, "method": "user.delUser"}' \
       http://192.168.1.104:1237/

Output:

{"id": null, "result": "", "error": null}

Empty result message means the user deleted successfully.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment