User Tools

Site Tools


howto:xml

XML

Enable API

You need to enable the usage of the XML-API in the HSMX under Periphery > XML Server.

Usage

You can reach these APIs via: http(s)://<HSMX>/xml/command.php with UTF-8 encoding.

  • get_users
  • add_user
  • delete_users
  • update_users
  • add_plan
  • login_user
  • logout_user
  • get_sessions
  • get_all_sessions
  • get_devices
  • delete_sessions
  • reset_password
  • get_locations
  • update_location
  • apply_white
  • add_walled_garden
  • remove_walled_garden
  • get_walled_garden
  • add_mac_based_user
  • remove_mac_based_user
  • health_status

get_users

Request

  • from and to are optional and can be cleverly used to do Pagination.
  • return is optional, defaults to <return>user</return> and can be:
    • count, which will return the amount of subscribers.
    • user, lastname, firstname, country, state, zip, street, city, email, phone, fax, free, room, added, status (0 = unused, 1 = idle, 2 = active, 3 = expired), user_create, payment, company.
    • plan, price, session_timeout, volume_up, volume_down, expiration, expire_time, start_date, expire_creation, limit_mac, band_up, band_down, url_redirect, ip_upsell, sim_use, idle_timeout, acc_interim, policy, qos_profile
  • orderby is optional
  • where is optional
    • field, operator and value are optional but defaults to omission of where
    • field can have one of the values of return or can be mac (added in 5.1.07)
    • operator comes from PostgreSQL Operator (official documentation)
<hsmx>
	<command>get_users</command>
	<return>user,idle_timeout,plan</return>
	<where>
		<field>user</field>
		<operator>~</operator>
		<value>free_.*</value>
	</where>
	<from></from>
	<to></to>
	<order_by></order_by>
</hsmx>

Responses

Success
  • <user[userid]> has zero to n occurrences.
  • <[field]> user is always present in responses.
<hsmx><user[userid]><[field]>[value]</[field]></user[userid]></hsmx>
Failure
<hsmx><result>2</result><description>Unsupported return field [return-field] .</description></hsmx>

add_user

Request

  • username is optional and will be generated for you.
    • but if specified password becomes required.
  • plan is mandatory.
  • registration_form is optional, if given it triggers the use of registration forms for processing input data.
  • Optional fields can be composed from:
    • user, lastname, firstname, country, state, zip, street, city, email, phone, fax, free, room, added, status (0 = unused, 1 = idle, 2 = active, 3 = expired), user_create, payment, company
    • price, session_timeout, volume_up, volume_down, expiration, expire_time (expire account after n seconds), start_date, expire_creation (expire account after creation), limit_mac, band_up, band_down, url_redirect, ip_upsell, sim_use, idle_timeout, acc_interim, policy, qos_profile.
    • Self defined custom fields.
<hsmx>
	<command>add_user</command>
	<username></username>
	<password></password>
	<plan></plan>
	<registration_form></registration_form> //overwrites everything
	<fields>
		<idle_timeout>60</idle_timeout>
		<firstname>Test</firstname>
	</fields>
</hsmx>

Responses

Success

If registration_form is specified:

<hsmx><result>1</result><description>OK</description><username>'.$username.'</username><password>'.$pass.'</password></hsmx>

Else if username and/or password is given:

<hsmx><result>1</result><description>OK</description></hsmx>

Otherwise we return:

<hsmx><result>1</result><description>OK</description><username>'.$username.'</username><password>'.$password.'</password></hsmx>
Failure

If registration_form is specified in the XML request but the registration form itself is missing:

<hsmx><result>2</result><description>Registration form not found</description></hsmx>

or when something went wrong trying to process the registration form:

<hsmx><result>2</result><description>[error-message]</description></hsmx>

Without registration_form when unable to generate or lacking username or password:

<hsmx><result>2</result><description>Missing username / password tag</description></hsmx>

or the username and password contain illegal characters. The valid classes are: +, -, @, ., a-z (and capitalized) and numbers.

<hsmx><result>2</result><description>Invalid characters for username / password tag</description></hsmx>

or the specified username already exists:

<hsmx><result>2</result><description>Username already exists</description></hsmx>

delete_users

Request

  • where is mandatory
    • field can be:
      • user, lastname, firstname, country, state, zip, street, city, email, phone, fax, free, room, added, status (0 = unused, 1 = idle, 2 = active, 3 = expired), user_create, payment, company, price, session_timeout, volume_up, volume_down, expiration, expire_time, start_date, expire_creation, limit_mac, band_up, band_down, url_redirect, ip_upsell, sim_use, idle_timeout, acc_interim, policy, qos_profile.
    • operator comes from PostgreSQL Operator (official documentation)
<hsmx> 
	<command>delete_users</command>
	<where>
		<field>user</field>
		<operator>~</operator>
		<value>free_.*</value>
	</where>
</hsmx>

Responses

Success
<hsmx><result>1</result><description>OK</description><removed>[count-of-deleted-subscribers]</removed></hsmx>
Failure
<hsmx><result>2</result><description>No subscribers found.</description></hsmx>

update_users

  • fields is mandatory and can be one of the following:
    • user, lastname, firstname, country, state, zip, street, city, email, phone, fax, free, room, added, status (0 = unused, 1 = idle, 2 = active, 3 = expired), user_create, payment, company, price, session_timeout, volume_up, volume_down, expiration, expire_time, start_date, expire_creation, limit_mac, band_up, band_down, url_redirect, ip_upsell, sim_use, idle_timeout, acc_interim, policy, qos_profile.
    • or self defined custom fields.
  • where is mandatory
    • field has the same properties and restrictions as fields.
    • operator comes from PostgreSQL Operator (official documentation)

Request

<hsmx>
	<command>update_users</command>
	<fields>
		<country>Belgium</country>
		<street>Sesame street 14</street>
		<Date of birth>01/02/2014</Date of birth>
		<price>50</price>
	</fields>
	<where>
		<field>user</field>
		<operator>~</operator>
		<value>free_.*</value>
	</where>
</hsmx>

Responses

Success
<hsmx><result>1</result><description>OK</description><updated>||#OFUPDATEDSUBSCRIBERS||</updated></hsmx>
Failure
<hsmx><result>2</result><description>No subscribers found.</description></hsmx>

add_plan

Request

  • username is mandatory.
  • fields is optional and may contain:
    • price, session_timeout, volume_up, volume_down, expiration, expire_time, start_date, expire_creation, limit_mac, band_up, band_down, url_redirect, ip_upsell, sim_use, idle_timeout, acc_interim, policy, qos_profile.
  • activate is optional, if this parameter is set the changes will be applied immediately.
<hsmx>
	<command>add_plan</command>
	<username>myuser</username>
	<plan>154</plan>
	<fields>
		<idle_timeout>60</idle_timeout>
		<firstname>Test</firstname>
	</fields>
</hsmx>

Responses

Success
<hsmx><result>1</result><description>OK</description></hsmx>
Failure

If the username was not specified in the request; we return:

<hsmx><result>2</result><description>Missing username.</description></hsmx>

If we can't find the specified username in our system:

<hsmx><result>2</result><description>User not found</description></hsmx>

login_user

Request

  • username and password are mandatory
  • mac or ip is mandatory (one or both)
  • vlan is optional
<hsmx>
	<command>login_user</command>
	<username>test</username>
	<password>test</password>
	<mac>00:00:00:00:00:00</mac>
	<ip>192.168.1.10</ip>
	<vlan>100</vlan>
</hsmx>

Responses

Success
<hsmx><result>1</result><description>OK</description></hsmx>
<hsmx><result>2</result><description>User already valid</description></hsmx>
Failure
<hsmx><result>2</result><description>Failed to activate user - ||USERNAME||</description></hsmx>
<hsmx><result>2</result><description>Required data missing</description></hsmx>
<hsmx><result>2</result><description>Unknown MAC address</description></hsmx>

logout_user

Request

  • username is mandatory
  • ip or mac is mandatory
<hsmx>
    <command>logout_user</command>
    <username>test</username>
    <mac>00:00:00:00:00:00</mac>
    <ip>192.168.1.10</ip>
</hsmx>

Responses

Success
<hsmx><result>1</result><description>OK</description></hsmx>
Failure
<hsmx><result>2</result><description>User is not active.</description></hsmx>

get_sessions

Request

  • username is mandatory.
  • Allowed values for return and order_by: \\acctstarttime, nasidentifier, acctstoptime, acctsessiontime, acctoutputoctets, acctinputoctets, framedipaddress, callingstationid, calledstationid, acctterminatecause.
  • order_by is optional.
<hsmx>
	<command>get_sessions</command>
	<username>test</username>
	<return>acctstarttime,nasidentifier,acctstoptime,acctsessiontime,acctoutputoctets,acctinputoctets,framedipaddress,callingstationid,calledstationid,acctterminatecause</return>
	<order_by>acctstarttime</order_by>
</hsmx>

Responses

Success
  • session<id> can appear 0 to n times.
<hsmx><session[sessionid]><[field-name]>[value]</[field-name]></session[sessionid]></hsmx>
Failure
<hsmx><result>2</result><description>Missing username tag</description></hsmx>
<hsmx><result>2</result><description>No valid return field</description></hsmx>

get_all_sessions

Request

  • Available in version 5.2.
  • acctstoptime and acctstoptime in the where clause can be a unix timestamp or formatted date (Y-m-d H:m:s).
  • Allowed values for where: \\session,user,acctstarttime,acctstoptime
  • where is optional
    • “field”, “operator” and “value” are optional but defaults to omission of “where”
    • “operator” comes from PostgreSQL Operator (official documentation)
  • Allowed values for return and order_by: \\session,acctstarttime,status,acctstarttime, nasidentifier, acctstoptime, acctsessiontime, acctoutputoctets, acctinputoctets, framedipaddress, callingstationid, calledstationid, acctterminatecause.
  • from and to are optional but should be used together to limit the result set
  • order_by is optional.
<hsmx>
        <command>get_all_sessions</command>
        <return>session,user,status,acctstarttime,nasidentifier,acctstoptime,acctsessiontime,acctoutputoctets,acctinputoctets,framedipaddress,callingstationid,calledstationid,acctterminatecause</return>
        <where>
            <field>acctstarttime</field>
            <operator>></operator>
            <value>1494241917</value>
        </where>
        <from>1</from>
        <to>100</to>
        <order_by>acctstarttime</order_by>
</hsmx>

Responses

Success
  • session<id> can appear 0 to n times.
<hsmx><session[sessionid]><[field-name]>[value]</[field-name]></session[sessionid]></hsmx>
Failure
<hsmx><result>2</result><description>No valid return field</description></hsmx>

get_devices

Request

  • username is mandatory.
<hsmx>
	<command>get_devices</command>
	<username>myusername</username>
</hsmx>

Responses

Success
  • device[deviceid] can appear 0 to n times.
  • mac is uppercased with dash separators.
<hsmx><device[deviceid]><mac>[mac-address]</mac></device[deviceid]></hsmx>
Failure
<hsmx><result>2</result><description>Missing username tag</description></hsmx>

delete_sessions

Request

  • field can only be username or mac.
  • where and it's children are mandatory.
<hsmx> 
	<command>delete_sessions</command>
	<where>
		<field>username</field>
		<operator>~</operator>
		<value>free_.*</value>
	</where>
</hsmx>

Responses

Success
<hsmx><result>1</result><description>OK</description><removed>[count-of-deleted-sessions]</removed></hsmx>
Failure
<hsmx><result>2</result><description>No sessions found.</description></hsmx>

reset_password

Request

  • username is mandatory.
<hsmx> 
	<command>reset_password</command>
	<username>myusername</username>
</hsmx>

Responses

Success
<hsmx><result>1</result><description>OK</description><password>[password]</password></hsmx>
Failure
<hsmx><result>2</result><description>Missing username</description></hsmx>
<hsmx><result>2</result><description>Invalid username</description></hsmx>

get_locations

Request

  • return has optional fields name, aaa_state, qos_profile, network_policy or content_filter.
<hsmx>
    <command>get_locations</command>
    <return>name,aaa_state,qos_profile,network_policy,content_filter</return>
</hsmx>

Responses

Success
<hsmx><location[id]><name></name><aaa_state></aaa_state><qos_profile_name></qos_profile_name><content_filter_name></content_filter_name></location[id]></hsmx>
Failure
<hsmx><result>2</result><description>No valid return field</description></hsmx>

update_location

Since version 5.1.06.

Request

  • location, qos, network_policy and content_filter are case insensitive.
  • aaa can be charge, open or close.
  • qos, network_policy and content_filter match by name or ID.
  • Settings are applied immediately but only to new subscribers, existing subscribers should re-authenticate to experience new settings.
<hsmx>
    <command>update_location</command>
    <location></location>
    <name></name>
    <aaa></aaa>
    <qos></qos>
    <network_policy></network_policy>
    <content_filter></content_filter>
</hsmx>

Responses

Success
<hsmx><result>1</result><description>OK</description></hsmx>
Failure
<hsmx><result>2</result><description>No location found</description></hsmx>

apply_white

Since version 5.1.06.

Request

  • white, sessiontime, maxdown and maxup are all positive integers expressed in minutes, or Kbit/s.
  • white and ip are mandatory.
  • time is optional and defaults to 600 minutes.
  • white refers to the whitelist ID.
  <hsmx>
    <command>apply_white</command>  
    <ip></ip>           
    <white></white>              
    <sessiontime></sessiontime>  
    <maxdown></maxdown>             
    <maxup></maxup>                
  </hsmx>

Responses

Success
<hsmx><result>1</result><description>OK</description></hsmx>
Failure
<hsmx><result>2</result><description>Required data missing</description></hsmx>
<hsmx><result>2</result><description>IP not found</description></hsmx>
<hsmx><result>2</result><description>User is already valid</description><username>[username]</username></hsmx>

add_walled_garden

Since version 5.1.16.

Request

  • advanced is used to add an advanced walled garden.
  • ip can also be a domain.
  • location can be the location id or location name.
  • action 1 is allowed, 2 is disallow.
  • protocol can be tcp,udp or imcp, leave empty for all.
Advanced walled garden
<hsmx>
     <command>add_walled_garden</command>
     <advanced>1</advanced>
     <ip>1.2.3.4</ip>
     <path></path>
     <location></location> 
     <action></action>
</hsmx>
Normal walled garden
<hsmx>
     <command>add_walled_garden</command>
     <ip>1.2.3.4</ip>
     <port></port>
     <protocol></protocol>
     <location></location>
</hsmx>

Responses

Success
<hsmx><result>1</result><description>Entry added</description></hsmx>
Failure
<hsmx><result>2</result><description>Entry already exists</description></hsmx>

remove_walled_garden

Since version 5.1.16.

Request

  • advanced is used to remove an advanced walled garden entry.
  • ip can also be a domain.
  • location can be the location id or location name.
  • action 1 is allowed, 2 is disallow.
  • protocol can be tcp,udp or imcp, leave empty for all.
Advanced walled garden
<hsmx>
     <command>remove_walled_garden</command>
     <advanced>1</advanced>
     <ip>1.2.3.4</ip>
     <path></path>
     <location></location> 
     <action></action>
</hsmx>
Normal walled garden
<hsmx>
     <command>remove_walled_garden</command>
     <ip>1.2.3.4</ip>
     <port></port>
     <protocol></protocol>
     <location></location>
</hsmx>

Responses

Success
<hsmx><result>1</result><description>Entry removed</description></hsmx>
Failure
<hsmx><result>2</result><description>Entry not found</description></hsmx>

get_walled_garden

Since version 5.1.16.

Request

  • advanced is used to retrieve the advanced list.
Advanced walled garden
<hsmx>
     <command>get_walled_garden</command>
     <advanced>1</advanced>
</hsmx>
Normal walled garden
<hsmx>
      <command>get_walled_garden</command>
</hsmx>

Responses

Advanced walled garden
<hsmx><entries><entry><ip></ip><path></path><action></action><location></location></entry><entry>...</entry></entries></hsmx>
Normal walled garden
<hsmx><entries><entry><ip></ip><port></port><protocol></protocol><location></location></entry><entry>...</entry></entries></hsmx>

add_mac_based_user

Since version 5.1.16.

Request

  • mac is mandatory and can be with : - or no separator.
  • username is optional
  • status 1 is active, 0 is blocked.
<hsmx>
     <command>add_mac_based_user</command>
     <mac>00-00-00-00-00-00</mac>
     <username></username>
     <status>1</status>
</hsmx>

Responses

Success
<hsmx><result>1</result><description>OK</description></hsmx>
Failure
<hsmx><result>2</result><description>User already exists</description></hsmx>

remove_mac_based_user

Since version 5.1.16.

Request

  • mac is mandatory and can be with : - or no separator.
<hsmx>
     <command>remove_mac_based_user</command>
     <mac>00-00-00-00-00-00</mac>
</hsmx>

Responses

Success
<hsmx><result>1</result><description>OK</description></hsmx>
Failure
<hsmx><result>2</result><description>MAC Address not found</description></hsmx>

health_status

Since version 5.2.01.

Request

<hsmx>
     <command>health_status</command>
</hsmx>

Responses

  • status 0: ok (no message tag), 1: warning, 2: critical
<hsmx><status>1</status><message>...</message></hsmx>

Examples

In xml we describe a few subscriber flows you can use with the XML-API.

Notes

Please contact support for information about legacy APIs.

howto/xml.txt · Last modified: 2017/07/20 10:11 by admin