Sherpa API Information
The Sherpa client is based upon 2 cosign protected web services. These services take inputs as standard CGI parameters and return JSON formatted output.
Generally the planning service is used to figure out the design of the vlan, then the provisioning service is used to request a vlan be created, edited, or removed now or sometime in the future.
To facilitate programatic access we provide a client side perl library which allows you to interact with our cosign protected webservices directly.
In addition, we provide a few demo perl scripts.
GRNOC::Sherpa::Planning
Description
Sherpa Planning Service
Location
https://sherpa.grnoc.iu.edu/service/planning.cgi
Methods
get_available_vlan_id
get_entities
get_interfaces
get_shortest_path
get_trunks
get_vlan_path
get_vlan_root_bridge
get_vlan_schedule
get_vlans
get_workgroups
is_vlan_id_available
get_available_vlan_id
Output Type
text/plain
Input Parameters:
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: vlan_id
Pattern: ^(\d+)$
Required: No
Description: optional vlan id/tag, if this is provided we check this specific tag or return the closest next avail.
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Description:
Returns a vlan id that is available for use
get_entities
Output Type
text/plain
Input Parameters:
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Description:
Returns the list of entities that can be assign to a vlan by users in the specified workgroup
get_interfaces
Output Type
text/plain
Input Parameters:
Name: node_name
Pattern: ^((\w+\.?)+)$
Required: Yes
Description: the node with interfaces you want to know about
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Description:
Returns the list interfaces on a node upon which a workgroup is allowed to set vlan endpoints
get_shortest_path
Output Type
text/plain
Input Parameters:
Name: node_z
Pattern: ^((\w+\.?)+)$
Required: Yes
Description: the other endpoint node eg \"chic.layer2.nlr.net\"
Name: node_a
Pattern: ^((\w+\.?)+)$
Required: Yes
Description: one of the endpoint nodes eg \"denv.layer2.nlr.net\"
Name: reserved_bandwidth
Pattern: ^(\d+)$
Required: Yes
Description: amount of available bandwidth to check for on each trunk
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Description:
Returns the shortest available path between node a and z. Checks for sufficient bandwidth.
get_trunks
Output Type
text/plain
Input Parameters:
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Description:
Returns the list of trunks available for use by the wg
get_vlan_path
Output Type
text/plain
Input Parameters:
Name: ckt_id
Pattern: ^(\d+)$
Required: Yes
Description: the vlan's ckt id
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Description:
Returns the set of trunks the vlan currently traverses
get_vlan_root_bridge
Output Type
text/plain
Input Parameters:
Name: ckt_id
Pattern: ^(\d+)$
Required: Yes
Description: the vlan's ckt id
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Description:
Returns the specified root bridge (not the current acting)
get_vlan_schedule
Output Type
text/plain
Input Parameters:
Name: ckt_id
Pattern: ^(\d+)$
Required: Yes
Description: database ckt_id
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Description:
Returns the pending scheduled events for the specified vlan
get_vlans
Output Type
text/plain
Input Parameters:
Name: search
Pattern: ^(\w+)$
Required: No
Description: Optional search routine to search for vlans by name, description, or vlan id content
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Description:
provides the set of vlans a user in the specified workgroup is allowed to manipulate
get_workgroups
Output Type
text/plain
Input Parameters:
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Description:
Returns the list of workgroups the remote user is allowed to use
is_vlan_id_available
Output Type
text/plain
Input Parameters:
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: vlan_id
Pattern: ^(\d+)$
Required: Yes
Description: vlan tag/id to check
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Description:
tests if the vlan tag is available for use
GRNOC::Sherpa::Provisioning
Description
Sherpa VLAN Provisioning
Location
https://sherpa.grnoc.iu.edu/service/provisioning.cgi
Methods
add_reservation
edit_vlan
get_reservations
get_status
is_edit_intrusive
provision_vlan
remove_reservation
remove_scheduled_edit
remove_vlan
schedule_add
schedule_edit
schedule_remove
add_reservation
Output Type
text/plain
Input Parameters:
Name: description
Pattern: ^((\w+|\||\s+|:|\#+|\-|\=)+)$
Required: Yes
Description: description of why these tags are reserved (for your use)
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: vlan_id2
Pattern: ^(\d+)$
Required: No
Description: second tag, used when reserving a range of tag
Name: vlan_id
Pattern: ^(\d+)$
Required: Yes
Description: first vlan tag
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Description:
reserves one or more vlan tags
edit_vlan
Output Type
text/plain
Input Parameters:
Name: root_bridge
Pattern: ^((\w+\.)*(\w*))$
Required: Yes
Description: the node you want to be the root of the vlan spanning tree
Name: node_z
Pattern: ^((\w+\.)*(\w*))$
Required: Yes
Description: the Z end node name
Name: int_a
Pattern: ^((\w|-)+(\d+\/?:?)+)$
Required: Yes
Description: the A end interface name
Name: node_a
Pattern: ^((\w+\.)*(\w*))$
Required: Yes
Description: the A end node name
Name: path
Pattern: ^(((\w+-\w+-\w+-\w+-\d+)\s*)+)$
Required: Yes
Description: comma separated list trunk ckts upon which this vlan should ride
Name: reserved_bandwidth
Pattern: ^(\d+)$
Required: Yes
Description: amount of bandwidth to reserve in bits per second
Name: description
Pattern: ^((\w+|\||\s+|:|\#+|\-|\=)+)$
Required: Yes
Description: vlan description
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: vlan_id
Pattern: ^(\d+)$
Required: Yes
Description: vlan id aka tag
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Name: int_z
Pattern: ^((\w|-)+(\d+\/?:?)+)$
Required: Yes
Description: the Z end interface name
Name: entity_id
Pattern: ^(\d+)$
Required: Yes
Description: associated entity
Name: request_id
Pattern: ^(\d+)$
Required: Yes
Description: integer id for tracking request
Description:
modify an existing vlan
get_reservations
Output Type
text/plain
Input Parameters:
Name: search
Pattern: ^(\w+)$
Required: No
Description: optional search pattern
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Description:
Returns the list reserved_vlans
get_status
Output Type
text/plain
Input Parameters:
Name: request_id
Pattern: ^(\d+)$
Required: Yes
Description: id used at time of provisioning
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: vlan_id
Pattern: ^(\d+)$
Required: Yes
Description: vlan tag for this vlan
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Description:
checks the provisioning status of a vlan
is_edit_intrusive
Output Type
text/plain
Input Parameters:
Name: root_bridge
Pattern: ^((\w+\.)*(\w*))$
Required: Yes
Description: the node you want to be the root of the vlan spanning tree
Name: node_z
Pattern: ^((\w+\.)*(\w*))$
Required: Yes
Description: the Z end node name
Name: int_a
Pattern: ^((\w|-)+(\d+\/?:?)+)$
Required: Yes
Description: the A end interface name
Name: node_a
Pattern: ^((\w+\.)*(\w*))$
Required: Yes
Description: the A end node name
Name: path
Pattern: ^(((\w+-\w+-\w+-\w+-\d+)\s*)+)$
Required: Yes
Description: comma separated list trunk ckts upon which this vlan should ride
Name: reserved_bandwidth
Pattern: ^(\d+)$
Required: Yes
Description: amount of bandwidth to reserve in bits per second
Name: description
Pattern: ^((\w+|\||\s+|:|\#+|\-|\=)+)$
Required: Yes
Description: vlan description
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: vlan_id
Pattern: ^(\d+)$
Required: Yes
Description: vlan id aka tag
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Name: int_z
Pattern: ^((\w|-)+(\d+\/?:?)+)$
Required: Yes
Description: the Z end interface name
Name: entity_id
Pattern: ^(\d+)$
Required: Yes
Description: associated entity
Description:
test proposed changed to see if they will interrupt packet forwarding
provision_vlan
Output Type
text/plain
Input Parameters:
Name: root_bridge
Pattern: ^((\w+\.)*(\w*))$
Required: Yes
Description: the node you want to be the root of the vlan spanning tree
Name: node_z
Pattern: ^((\w+\.)*(\w*))$
Required: Yes
Description: the Z end node name
Name: int_a
Pattern: ^(\w+(\d+\/?:?)+)$
Required: Yes
Description: the A end interface name
Name: node_a
Pattern: ^((\w+\.)*(\w*))$
Required: Yes
Description: the A end node name
Name: path
Pattern: ^(((\w+-\w+-\w+-\w+-\d+)\s*)+)$
Required: Yes
Description: comma separated list trunk ckts upon which this vlan should ride
Name: reserved_bandwidth
Pattern: ^(\d+)$
Required: Yes
Description: amount of bandwidth to reserve in bits per second
Name: description
Pattern: ^((\w+|\||\s+|:|\#+|\-|\=)+)$
Required: Yes
Description: vlan description
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: vlan_id
Pattern: ^(\d+)$
Required: Yes
Description: vlan id aka tag
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Name: int_z
Pattern: ^(\w+(\d+\/?:?)+)$
Required: Yes
Description: the Z end interface name
Name: entity_id
Pattern: ^(\d+)$
Required: Yes
Description: associated entity
Name: decom_date
Pattern: ^(\d+)$
Required: No
Description: Optional time this vlan should be removed, in unix epoch
Name: request_id
Pattern: ^(\d+)$
Required: Yes
Description: integer id used to reference this request
Description:
creates a vlan on the network
remove_reservation
Output Type
text/plain
Input Parameters:
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: vlan_id
Pattern: ^(\d+)$
Required: Yes
Description: vlan tag
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Description:
removes the specified reservation
remove_scheduled_edit
Output Type
text/plain
Input Parameters:
Name: sched_id
Pattern: ^(\d+)$
Required: Yes
Description: schedule record id
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Description:
removes the specified edit from the scheduler queue
remove_vlan
Output Type
text/plain
Input Parameters:
Name: request_id
Pattern: ^(\d+)$
Required: Yes
Description: request tracking id
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: vlan_id
Pattern: ^(\d+)$
Required: Yes
Description: vlan_id aka tag you want to remove
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Description:
removes the specified vlan from the network
schedule_add
Output Type
text/plain
Input Parameters:
Name: activation_date
Pattern: ^(\d+)$
Required: Yes
Description: time this modification should become active, in unix epoch
Name: root_bridge
Pattern: ^((\w+\.)*(\w*))$
Required: Yes
Description: the node you want to be the root of the vlan spanning tree
Name: node_z
Pattern: ^((\w+\.)*(\w*))$
Required: Yes
Description: the Z end node name
Name: int_a
Pattern: ^((\w|-)+(\d+\/?:?)+)$
Required: Yes
Description: the A end interface name
Name: node_a
Pattern: ^((\w+\.)*(\w*))$
Required: Yes
Description: the A end node name
Name: path
Pattern: ^(((\w+-\w+-\w+-\w+-\d+)\s*)+)$
Required: Yes
Description: comma separated list trunk ckts upon which this vlan should ride
Name: reserved_bandwidth
Pattern: ^(\d+)$
Required: Yes
Description: amount of bandwidth to reserve in bits per second
Name: description
Pattern: ^((\w+|\||\s+|:|\#+|\-|\=)+)$
Required: Yes
Description: vlan description
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: vlan_id
Pattern: ^(\d+)$
Required: Yes
Description: vlan id aka tag
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Name: int_z
Pattern: ^((\w|-)+(\d+\/?:?)+)$
Required: Yes
Description: the Z end interface name
Name: entity_id
Pattern: ^(\d+)$
Required: Yes
Description: associated entity
Name: decom_date
Pattern: ^(\d+)$
Required: No
Description: Optional time this vlan should be removed, in unix epoch
Description:
add a new vlan some time in the future
schedule_edit
Output Type
text/plain
Input Parameters:
Name: activation_date
Pattern: ^(\d+)$
Required: Yes
Description: time this modification should become active, in unix epoch
Name: root_bridge
Pattern: ^((\w+\.)*(\w*))$
Required: Yes
Description: the node you want to be the root of the vlan spanning tree
Name: node_z
Pattern: ^((\w+\.)*(\w*))$
Required: Yes
Description: the Z end node name
Name: int_a
Pattern: ^((\w|-)+(\d+\/?:?)+)$
Required: Yes
Description: the A end interface name
Name: node_a
Pattern: ^((\w+\.)*(\w*))$
Required: Yes
Description: the A end node name
Name: path
Pattern: ^(((\w+-\w+-\w+-\w+-\d+)\s*)+)$
Required: Yes
Description: comma separated list trunk ckts upon which this vlan should ride
Name: reserved_bandwidth
Pattern: ^(\d+)$
Required: Yes
Description: amount of bandwidth to reserve in bits per second
Name: description
Pattern: ^((\w+|\||\s+|:|\#+|\-|\=)+)$
Required: Yes
Description: vlan description
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: vlan_id
Pattern: ^(\d+)$
Required: Yes
Description: vlan id aka tag
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Name: int_z
Pattern: ^((\w|-)+(\d+\/?:?)+)$
Required: Yes
Description: the Z end interface name
Name: entity_id
Pattern: ^(\d+)$
Required: Yes
Description: associated entity
Description:
modify an existing vlan some time in the future
schedule_remove
Output Type
text/plain
Input Parameters:
Name: decom_date
Pattern: ^(\d+)$
Required: Yes
Description: time this vlan should be removed, in unix epoch
Name: net
Pattern: ^(\d+)$
Required: Yes
Description: The administrative network identifier
Name: vlan_id
Pattern: ^(\d+)$
Required: Yes
Description: vlan_id aka tag you want to remove
Name: wg
Pattern: ^(\d+)$
Required: Yes
Description: The workgroup identifier
Description:
removes the vlan from the network at a later time
