1 of 28
NAC Request Tool
The NAC Request Tool enables you to perform the following functions using a CLI-based
request:
l Add or remove a MAC address to or from an end-system group or "Deny List."
l Add or remove users to and from user groups.
l Add or remove an end-system from a group and reauthenticate the end-system.
l Add, delete, or update registered users or devices.
l Delete an end-system in ExtremeCloud™ IQ - Site Engine
l Add, delete, or update devices in ExtremeCloud IQ - Site Engine.
l Perform a forced reauthentication or a forced reauthentication and scan of end-systems.
l Add or remove a MAC lock on an end-system.
l Update end-system custom fields.
l Export the entire end-system table in the ExtremeCloud IQ - Site Engine database to a .csv file.
l Print or export the members of an end-system or user group.
l Display end-system, ExtremeCloud IQ - Site Engine device, or registration information.
l Import and export devices in ExtremeCloud IQ - Site Engine using an .ngf file.
l Add or update ExtremeCloud IQ - Site Engine profiles and credentials.
l Add or update CLI credentials.
l Update the local NAC Request Tool Truststore with the ExtremeCloud IQ - Site Engine server certificate.
The tool can perform an operation on a single end-system or user using the single command
line, or it can perform an operation on multiple end-systems and users through the use of a CSV
(Comma Separated Value) file.
NOTE: If you are running NetSight version 5.0 or higher, you must use a NAC Request Tool version of 5.0 or
higher.
Deploying the NAC Request Tool
To deploy the NAC Request Tool, unzip the contents of the NacRequestTool.zip file to a
directory of your choice.
Open a shell and "cd" to the directory where you installed the tool.
Performing a Request
2 of 28
NOTE: You must be a member of an ExtremeCloud IQ - Site Engine authorization group that has the
ExtremeCloud IQ - Site Engine NAC Manager > "Read/Write access to the NAC Web Services APIs"
capability selected in order to use the NAC Request Tool.
Performing a Request
The NAC Request Tool uses the following command line argument to perform a request.
NacRequest -server <X1> -username <X2> -password <X3> [ options ]
where:
X1 is the IP address of the ExtremeCloud IQ - Site Engine Server
X2 is the user’s ExtremeCloud IQ - Site Engine username
X3 is the user’s ExtremeCloud IQ - Site Engine password
Using a CFG File
You can create a .cfg file in the working directory to contain your username and password
credentials as an alternative to using the command line arguments. You can also include the
optional httpsport parameter in the .cfg file, if desired. When both the .cfg file and command line
arguments are specified, the command line arguments take precedence.
In the .cfg file, each parameter should be specified on a separate line using either of the
following formats. Escape characters are necessary in the .cfg file if "\" is used.
username <X2>
password <X3>
httpsport <X4>
or
username=<X2>
password=<X3>
httpsport=<X4>
where:
X2 is the user’s ExtremeCloud IQ - Site Engine username
X3 is the user’s ExtremeCloud IQ - Site Engine password
X4 is the ExtremeCloud IQ - Site Engine server HTTPS port (default 8443)
Command Line Options
The following table describes the possible command line options that you can use when sending
a NAC Request Tool command. Keep in mind the following considerations when sending a
request:
Performing a Request
3 of 28
l The -server, -username, and -password options are required.
l If you specify an option in the command line, you must also specify a value.
l If an option is not specified in the command line, then the default value (if there is one) is used. The
values listed below in bold typeface are the defaults for the given option.
l If the -csv option is used, all other options (except the required options) are ignored.
Option Description Values Required?
-server IP address of the ExtremeCloud IQ - Site Engine
Server.
For example, 10.20.30.40 Yes
-username The user’s ExtremeCloud IQ - Site Engine username. <username> Yes
-password The user’s ExtremeCloud IQ - Site Engine password. <mypassword> Yes
-httpsport The ExtremeCloud IQ - Site Engine server HTTPS port. <HTTPS port number>
(default is 8443)
No
-timeout The amount of time before the request is terminated. The amount of time specified
in milliseconds.
No
-oper The type of operation for this request. Possible values are:
info
acceptcert
clicredential
endsystemcsv
esdelete
esoverride
maclock
nscredential
nsdevice
nsprofile
reauth
reauthandscan
regdevice
reguser
saveinfo
useroverride
No
-user The user identifier. This option is only for use with the
useroverride operation.
<user name> No
-type The end-system identifier type. This option is only for
use with esoverride operations. If it is not specified,
the end-system type defaults to full MAC address.
Possible values are:
FULL_MAC
FULL_IP
HOSTNAME
No
-endsystem The MAC address, IP address, or Hostname of the
end-system. For MAC address, this option is for use
with esoverride, reauth, info, maclock and saveinfo
operations. For IP address and Hostname, this option
is only for use with esoverride operations.
<MAC address>, <IP
address>, or <Hostname>
No
-deviceip The IP address of an ExtremeCloud IQ - Site Engine
device. This option is for use with the info operation.
<IP address> No
-reginfo This option is for use with the info operation to
provide an extended set of information on the
registered device and registered user associated with
the MAC address.
<MAC address> No
Command Line Options
Performing a Request
4 of 28
Option Description Values Required?
-hr This option is for use with the info operation to print
the most recent health result and vulnerabilities for an
end-system. The output is printed in xml, and is
meant to be used by a tool that can parse the xml
format and extract the details.
None No
-descr A description of the override. Valid for esoverride and
useroverride operations.
"<description>" No
-group The target end-system or user group. This option is
valid for info, esoverride, and useroverride operations.
"<end-system group>" or
"<user group>". Use "Deny
List" to add end-system to
Deny List group.
No
-add Add an end-system or user to a group, create a
registered user or registered device, add an end-
system MAC lock, add a device to ExtremeCloud IQ -
Site Engine, add a profile or a credential to
ExtremeCloud IQ - Site Engine. This option is valid for
esoverride, useroverride, reguser, regdevice, maclock,
nsdevice, nsprofile, nscredential, and clicredential
operations. For esoverride and useroverride
operations, the end-system or user is removed from
other groups of which they are already a member.
None No
-addAndReauth Add an end-system to a group and then
reauthenticate the end-system. This option is valid for
the esoverride operation.
None No
-add -noremove Add an end-system or user to a group. The end-
system or user will not be removed from other groups
of which they are already a member. This option is
valid for esoverride and useroverride operations.
None No
-del Delete an end-system or user from a group, delete a
registered user or registered device, delete an end-
system MAC lock, or delete a device from
ExtremeCloud IQ - Site Engine. This option is valid for
esoverride, useroverride, reguser, regdevice, maclock,
and nsdevice operations.
None No
-delAndReauth Delete an end-system from a group and then
reauthenticate the end-system. This option is valid for
the esoverride operation.
None No
-update Update the properties of a device in ExtremeCloud IQ
- Site Engine. Update a profile or a credential in
ExtremeCloud IQ - Site Engine. This option is valid for
nsdevice, reguser, regdevice, nsprofile, nscredential,
and clicredential operations.
None No
-import Import a list of ExtremeCloud IQ - Site Engine devices
using a text file that was created in ExtremeCloud IQ -
Site Engine Generated Format (.ngf file). This option
is valid for nsdevice operations.
Path to the file to import. For
example,
C:\Users\User\import.ngf
No
-export Export a device list from ExtremeCloud IQ - Site
Engine to a text file created in ExtremeCloud IQ - Site
Engine Generated Format (.ngf file). This option is
valid for nsdevice operations.
Path to where the file should
be saved. For example,
C:\Users\User\export.ngf
No
Command Line Options
Performing a Request
5 of 28
Option Description Values Required?
-csv Path and name of a CSV file. This is used to create
multiple overrides. This option is valid for reauth,
reauthandscan, esoverride, useroverride, reguser, and
regdevice, operations.
For example,
"c:\myNACRequests.txt"
No
Command Line Options
Performing a Request
6 of 28
Option Description Values Required?
-properties A comma-separated list of properties. This option is
valid for reguser, regdevice, nsdevice, nsprofile,
nscredential, and clicredential operations.
Properties for adding and
deleting registered users:
applianceGroup*, userName*,
userTypeStr*, firstName,
middleName, lastName,
emailAddress, sponsor,
startTime, expiresTime,
userData1, userData2,
userData3, userData4,
userData5.
Properties for updating
registered users:
applianceGroup, userName*,
userTypeStr, firstName,
middleName, lastName,
emailAddress, sponsor,
startTime, expiresTime,
userData1, userData2,
userData3, userData4,
userData5.
Properties for adding
registered devices:
applianceGroup*, userName*,
macAddress*, stateStr*,
ipAddress, sponsor,
sponsorDeviceGroup,
description.
Properties for deleting
registered devices:
applianceGroup*, userName*,
macAddress*, stateStr,
ipAddress, sponsor,
sponsorDeviceGroup,
description.
Properties for updating
registered devices:
applianceGroup, userName,
macAddress*, stateStr,
ipAddress, sponsor,
sponsorDeviceGroup,
description.
Properties for adding an
ExtremeCloud IQ - Site
Engine device: ip*,
profileName*, snmpContext,
nickName.
Properties for deleting an
No
Command Line Options
Performing a Request
7 of 28
Option Description Values Required?
ExtremeCloud IQ - Site
Engine device: ip*.
Properties for updating an
ExtremeCloud IQ - Site
Engine device: ip*,
profileName, snmpContext,
nickName, userData1,
userData2, userData3,
userData4.
Properties for updating an
ExtremeCloud IQ - Site
Engine device: ip*,
profileName, snmpContext,
nickName, userData1,
userData2, userData3,
userData4.
Properties for adding an
ExtremeCloud IQ - Site
Engine Profile: name*,
snmpVersion*, read*, write*,
maxAccess*, authCred*.
Properties for updating an
ExtremeCloud IQ - Site
Engine Profile: name*, read*,
write*, maxAccess*,
authCred*.
Properties for adding an
ExtremeCloud IQ - Site
Engine Credential: name*,
snmpVersion*,
communityName**,
userName**, authPassword,
authType, privPassword,
privType.
Properties for updating an
ExtremeCloud IQ - Site
Engine Credential: name*,
communityName, userName,
authPassword, authType,
privPassword, privType.
Properties for adding a CLI
Credential: userName*,
description*, loginPassword*,
enablePassword*,
configurationPassword*,
type*.
Properties for updating a CLI
Credential: userName*,
description*, loginPassword,
Command Line Options
NAC Request Tool Operations
8 of 28
Option Description Values Required?
enablePassword,
configurationPassword, type.
*Indicates a mandatory
property.
** For SNMP v1 or v2,
communityName is required.
For SNMP v3, userName is
required.
-help Displays the available options. None No
-ex Provides an extended set of information for an end-
system. This option is valid for info operations.
None No
-switch IP address of the switch to which the end-system will
be locked. This option is valid for maclock operations.
For example, 10.20.30.40 No
-port Switch port to which the end-system will be locked.
This option is valid for maclock operations.
For example, ge.1.1 No
-reject Reject the authentication request if the end-system
tries to authenticate on a different switch/port. This
option is valid for maclock operations.
None No
-policy The policy that should be applied if the end-system
tries to authenticate on a different switch/port. This
option is valid for maclock operations.
For example, "Deny Access" No
-custom1
-custom2
-custom3
-custom4
Four custom fields used to display end-system
information. These options are valid for the saveinfo
operation.
For example, "asset tag 1234" No
-version Displays the NAC Request Tool version. None No
Command Line Options
NAC Request Tool Operations
This section provides descriptions of the different operations available with the NAC Request
Tool, and includes examples of command line usage and options for each operation.
NOTE: Following a NAC Request "override" operation, you must enforce the changes to your ExtremeControl
engines unless you have selected "Automatically update ExtremeControl engines" as a end-system or
user group option.
Add an End-System to an End-System Group
This request adds an end-system to the specified end-system group and removes the end-
system from all other end-system groups except the "Deny List" group. The specified end-
system group must exist in NAC Manager. Full MAC addresses, full IP addresses, and hostnames
are allowed as end-system identifiers for this operation, with the default being full MAC.
The -add, -oper, -endsystem, and -group options are all required. The -oper option requires the
esoverride value. The -type option is optional and defaults to full MAC address (FULL_MAC) if
not supplied. The -descr option is optional and defaults to an empty string if not supplied. If you
NAC Request Tool Operations
9 of 28
want to add an end-system to an end-system group, but you do not want to remove the end-
system from other groups of which it is already a member, use the -add -noremove option.
For example, the following command will add the end-system with a MAC address of
11:22:33:44:55:66 to the "Printer List" end-system group and remove the end-system from all
other end-system groups except the "Deny List" group.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -add -oper
esoverride -endsystem 11:22:33:44:55:66 -descr "South side printer" -group
"Printer List"
This example shows the command using the -type option to specify an IP address.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -add -oper
esoverride -type FULL_IP -endsystem 11.22.33.44 -descr "South side printer" -
group "Printer List"
Remove an End-System from an End-System Group
This request removes an end-system from the specified end-system group. Full MAC addresses,
full IP addresses, and hostnames are allowed as end-system identifiers for this operation, with
the default being full MAC.
The options -del, -oper, -endsystem, and -group are all required. The -oper option requires the
esoverride value. The -type option is optional and defaults to full MAC address (FULL_MAC) if
not supplied.
For example, the following command will delete the end-system with a MAC address of
11:22:33:44:55:66 from the "Printer List" end-system group but not the "Deny List" end-system
group.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -del -oper
esoverride -endsystem 11:22:33:44:55:66 -group "Printer List"
Add an End-System to an End-System Group and Reauthenticate
This request adds an end-system to an end-system group and then reauthenticates the end-
system.
The -addAndReauth, -oper, -endsystem, and -group options are all required. The -oper option
requires the esoverride value.
For example, the following command will add the end-system with a MAC address of
11:22:33:44:55:66 to the "Printer List" end-system group and then reauthenticate the end-
system.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -addAndReauth -
oper esoverride -endsystem 11:22:33:44:55:66
-group "Printer List"
NAC Request Tool Operations
10 of 28
Remove an End-System from an End-System Group and
Reauthenticate
This request deletes an end-system from an end-system group and then reauthenticates the
end-system.
The -delAndReauth, -oper, -endsystem, and -group options are all required. The -oper option
requires the esoverride value.
For example, the following command will remove the end-system with a MAC address of
11:22:33:44:55:66 from the "Printer List" end-system group and then reauthenticate the end-
system.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -delAndReauth -
oper esoverride -endsystem 11:22:33:44:55:66
-group "Printer List"
Blacklist an End-System
This request adds the end-system to the "Deny List" end-system group. If the end-system is a
member of another end-system group, it will remain a member of that group. Full MAC
addresses, full IP addresses, and hostnames are allowed as end-system identifiers for this
operation, with the default being full MAC.
The -add, -oper, -endsystem, and -group options are all required. The -oper option requires the
esoverride value. The -descr option is optional and defaults to an empty string if not supplied.
For example, the following command will add the end-system with a MAC address of
11:22:33:44:55:66 to the "Deny List" end-system group. If the end-system is a member of another
end-system group, it will remain a member of that group.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -add -oper
esoverride -endsystem 11:22:33:44:55:66 -descr "unauthorized access" -group
"Deny List"
Undo a Blacklist
This request removes the end-system from the "Deny List" end-system group. If the end-system
is a member of another end-system group, it will remain a member of that group. Full MAC
addresses, full IP addresses, and hostnames are allowed as end-system identifiers for this
operation, with the default being full MAC.
The -del, -oper, -endsystem, and -group options are all required. The -oper option requires the
esoverride value.
For example, the following command will delete the end-system with a MAC address of
11:22:33:44:55:66 from the "Deny List" end-system group. If the end-system is a member of
another end-system group, it will remain a member of that group.
NAC Request Tool Operations
11 of 28
NacRequest -server 10.20.33.2 -username admin -password pswd1 -del -oper
esoverride -endsystem 11:22:33:44:55:66 -group "Deny List"
Add a User to a User Group
This request adds a user to the specified user group. The specified group must exist in NAC
Manager.
The -add, -oper, -user, and -group options are all required. The -oper option requires the
useroverride value. The
-descr option is optional and defaults to an empty string if not supplied.
For example, the following command adds the end user with the user name of rjones to the
"Registered Users" user group and remove the end user from all other user groups of which it is
already a member.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -add -oper
useroverride -user rjones -descr "Enterprise User" -group "Registered Users"
If you want to add a user to a user group and then reauthenticate the end-system, use the -
addAndReauth option.
If you want to add a user to a user group, but you do not want to remove the user from other
groups of which it is already a member, use the -add -noremove option.
Remove a User from a User Group
This request removes a user from the specified user group.
The -del, -oper, -user, and -group options are all required. The -oper option requires the
useroverride value.
For example, the following command will delete the end user with the user name of rjones from
the "Registered Users" user group.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -del -oper
useroverride -user rjones -group "Registered Users"
Add, Delete, or Update a Registered User
This request adds or deletes a registered user to the Registration System Administration web
page or updates an existing registered user.
Add and Update Operations
The -add, -oper, and -properties options are all required. The -oper option requires the reguser
value. (See below for a list of -properties values.)
For example, the following command will add a registered end user with the user name jsmith.
NAC Request Tool Operations
12 of 28
NacRequest -server 10.20.33.2 -username admin -password pswd1 -add -oper
reguser -properties "applianceGroup=default,userName=jsmith,firstName=John,
lastName=Smith,userTypeStr=Guest"
Delete Operations
The -del, -oper, and -properties options are all required. The -oper option requires the reguser
value.
For example, the following command will delete a registered end user with the user name jsmith.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -del -oper
reguser -properties "applianceGroup=default,userName=jsmith,userTypeStr=Guest"
Properties Values
The -properties option is a comma-separated list that can include the following values for add,
delete, and update operations:
l applianceGroup - (required except for Update operations) the engine group that the registered user
belongs to.
l userName - (required) the login identifier of the registered user.
l userTypeStr - (required except for Update operations) the registered user's type. Valid values are
"Guest" and "Web Authentication."
l firstName - the registered user's first name.
l middleName - the registered user's middle name or middle initial.
l lastName - the registered user's last name.
l emailAddress - the registered user's email address.
l sponsor - the user who is sponsoring the registration of this user.
l startTime - the date and time when this registration begins. Valid formats are either SQL timestamp
format (for example, 2009-06-01 10:18:00) or as an integer (for example, 1241187430240).
l expiresTime - the date and time when this registration expires. Valid formats are either SQL timestamp
format (for example, 2009-06-01 10:18:00) or as an integer (for example, 1241187430240).
l userData1 - optional customer-defined data.
l userData2 - optional customer-defined data.
l userData3 - optional customer-defined data.
l userData4 - optional customer-defined data.
l userData5 - optional customer-defined data.
Add, Delete, or Update a Registered Device
This request adds or deletes a registered device to the Registration System Administration web
page or updates an existing registered device.
NAC Request Tool Operations
13 of 28
Add and Update Operations
The -add, -oper, and -properties options are all required. The -oper option requires the
regdevice value. (See below for a list of -properties values.)
For example, the following command will add a registered device.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -add -oper
regdevice -properties
"applianceGroup=default,userName=jsmith,macAddress=00:90:BF:55:55:58,stateStr
=Approved,ipAddress=10.20.32.18,sponsor=rjones,sponsorDeviceGroup=Registered
Guests"
Delete Operations
The -del, -oper, and -properties options are all required. The -oper option requires the regdevice
value.
For example, the following command will delete a registered device.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -del -oper
regdevice -properties
"applianceGroup=default,userName=jsmith,macAddress=00:90:BF:55:55:58"
Properties Values
The -properties option is a comma-separated list that can include the following values for add,
delete, and update operations:
l applianceGroup - (required except for Update operations) the engine group that the registered device
belongs to.
l userName - (required except for Update operations) the login identifier of the registered user
associated with the registered device. Note that the registered user must exist before the registered
device can be successfully created.
l macAddress - (required) the registered device's MAC address.
l stateStr - (required for Add operations) the registered devices's state. Valid values are "Pending,"
"Approved," "Denied," and "Suspended."
l ipAddress - the registered device's IP address.
l sponsor - the login identifier of the user who is sponsoring the registration of this device.
l sponsorDeviceGroup - the end-system group that the sponsor would like to place the device into.
l startTime - the date and time when this registration begins. Valid formats are either SQL timestamp
format (for example, 2009-06-01 10:18:00) or as an integer (for example, 1241187430240).
l description - a description of the registered device.
NAC Request Tool Operations
14 of 28
Reauthenticate an End-System
This request forces the ExtremeControl engines to reauthenticate an end-system so that the
end-system can receive its new access policy. Only full MAC addresses are allowed as end-
system identifiers for this operation.
The -oper and -endsystem options are required. The -oper option requires the reauth value.
For example, the following command forces the reauthentication of the end-system with a MAC
address of 11:22:33:44:55:66.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -oper reauth -
endsystem 11:22:33:44:55:66
Reauthenticate and Scan an End-System
This request forces the ExtremeControl engines to reauthenticate and scan an end-system so
that the end-system can receive its new access policy. Only full MAC addresses are allowed as
end-system identifiers for this operation.
The -oper and -endsystem options are required. The -oper option requires the reauthandscan
value.
For example, the following command will force the reauthentication and scan of the end-system
with a MAC address of 11:22:33:44:55:66.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -oper
reauthandscan -endsystem 11:22:33:44:55:66
Add a MAC Lock
This request adds a MAC Lock to an end-system. Only full MAC addresses are allowed as end-
system identifiers for this operation.
The -add, -oper, -endsystem, -switch, and either -policy or -reject options are all required. The -
oper option requires the maclock value.
For example, the following command will add a MAC lock on the end-system with a MAC
address of 11:22:33:44:55:66, specifying the switch and port the end-system will be locked to,
and the policy that should be applied if the end-system tries to authenticate on a different
switch/port.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -add -oper
maclock -endsystem 11:22:33:44:55:66 -switch 10.20.30.40 -port ge.1.1 -policy
"Deny Access"
The following command will add a MAC lock on the end-system with a MAC address of
11:22:33:44:55:66, specifying the switch the end-system will be locked to, and to reject the
authentication request if the end-system tries to authenticate on a different switch/port.
NAC Request Tool Operations
15 of 28
NacRequest -server 10.20.33.2 -username admin -password pswd1 -add -oper
maclock -endsystem 11:22:33:44:55:66 -switch 10.20.30.40 -reject
Remove a MAC Lock
This request removes a MAC Lock from an end-system. Only full MAC addresses are allowed as
end-system identifiers for this operation.
The -del, -oper, and -endsystem options are all required. The -oper option requires the maclock
value.
For example, the following command will remove the MAC lock on the end-system with a MAC
address of 11:22:33:44:55:66.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -del -oper
maclock -endsystem 11:22:33:44:55:66
Update End-System Custom Fields
This request updates custom field information for a specific end-system based on MAC address.
Only full MAC addresses are allowed as end-system identifiers for this operation.
The -oper, -endsystem, and -custom1, -custom2, -custom3, or -custom4 options are all required.
The -oper option requires the saveinfo value.
For example, the following command will update custom field 1 for the end-system with a MAC
address of 11:22:33:44:55:66 to the value of "asset tag 123."
NacRequest -server 10.20.33.2 -username admin -password pswd1 -oper saveinfo -
endsystem 11:22:33:44:55:66 -custom1 "asset tag 123"
Export the End-System Table
This request exports the entire end-system table in the ExtremeCloud IQ - Site Engine database
to a .csv file.
The -oper and -export options are required. The -oper option requires the endsystemcsv value.
For example, the following command will export the entire end-system table to
C:\Users\User\exportFile.csv.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -oper
endsystemcsv -export C:\Users\User\exportFile.csv
By default, the endsystemcsv operation will put quotes around all the properties in the output. If
you don’t want quotes around the properties, add a -noquotes option to the command. For
example:
NacRequest -server 10.20.33.2 -username admin -password pswd1 -oper
endsystemcsv -export C:\Users\User\exportFile.csv
-noquotes
NAC Request Tool Operations
16 of 28
Print or Export the Members of an End-System or User Group
This request retrieves all the members of an end-system group, user group, or other rule group,
and either prints the contents at the command prompt or exports the contents to a CSV file.
To print, the -oper and -group options are required. The -oper option requires the info value.
The following command will print the members of the Phones group at the command prompt.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -oper info -
group Phones
To export, the -oper, -group, and -export options are required. The -oper option requires the
info value.
The following command will export the members of the Phones group to a CSV file.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -oper info -
group Phones -export C:\Users\User\exportFile.csv
Delete an End-System in ExtremeCloud IQ - Site Engine
This request deletes an end-system in ExtremeCloud IQ - Site Engine, but enables you to
optionally preserve the following related end-system data:
l Custom information
l Group assignment
l MAC locks
l Registration and web authentication
The -oper and -endsystem options are required. The -oper option requires the esdelete value.
You can use the following options to delete the end-system but preserve related end-system
data. If these options are not used, the information will be deleted by default.
l The -keepcustom option deletes the end-system, but keeps the custom information.
l The -keepingroups option deletes the end-system, but keeps the group assignments.
l The -keepmacLocks option deletes the end-system, but keeps the MAC locks.
l The -keepreg option deletes the end-system, but keeps the registration and web authentication.
l The -donotforce option deletes the end-system if no errors occur, but does not force the delete of an
end-system if an SNMP error occurs on the switch. Additionally, deleting an end-system when an SNMP
error occurs on the switch with the -donotforce option selected causes the end-system to appear in the
end-system table as an end-system error event.
For example, the following command deletes the end-system with a MAC address of
11:22:33:44:55:66 but keeps the end-system’s custom information and group assignments.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -oper esdelete -
endsystem 11:22:33:44:55:66 -keepcustom
-keepingroups
NAC Request Tool Operations
17 of 28
Display End-System, ExtremeCloud IQ - Site Engine Device, and
Registration Info
This request displays end-system, ExtremeCloud IQ - Site Engine device, or registration related
information on the console.
The -oper option is required, and requires the info value.
Either the -endsystem option, the -deviceip option, or the -reginfo option is also required:
l The -endsystem option requests end-system info based on the end-system MAC address. The following
two options can be used with the -endsystem option:
l The -ex option provides an extended set of information for an end-system.
l The -hr option prints the most recent health result and vulnerabilities for an end-system. The
output is printed in xml, and is meant to be used by a tool that can parse the xml format and
extract the details.
l The -deviceip option requests ExtremeCloud IQ - Site Engine device info based on the device IP address.
l The -reginfo option provides an extended set of information on the registered device and registered
user associated with a MAC address.
For example, the following command will display information on the end-system with a MAC
address of 11:22:33:44:55:66.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -oper info -
endsystem 11:22:33:44:55:66
The following command will display information on the ExtremeCloud IQ - Site Engine device
with an IP address of 10.20.30.40.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -oper info -
deviceip 10.20.30.40
The following command will print health result and vulnerabilities information for an endsystem.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -endsystem
11:22:33:44:55:66 -oper info -hr
The following command will display information on the registered device and registered user
associated with the MAC address of 11:22:33:44:55:66.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -oper info -
reginfo 11:22:33:44:55:66
Add, Delete, or Update a Device in ExtremeCloud IQ - Site Engine
This request adds or removes a device to or from ExtremeCloud IQ - Site Engine. It can also be
used to update certain device properties in the ExtremeCloud IQ - Site Engine database.
NAC Request Tool Operations
18 of 28
Add Operations
The -add, -oper, and -properties options are all required. The -oper option requires the nsdevice
value.
The -properties option is a comma-separated list that can include the following values:
l ip - (required) the device's IP address.
l profileName - (required) the profile assigned to the device.
l snmpContext - the SNMP context that will be assigned to the device. An SNMP context is a collection of
MIB objects, often associated with an entity. By specifying the SNMP context, access is allowed to the
subset of MIB objects related to that context on the device.
l nickName - the nickname assigned to the device.
For example, the following command adds a device with the IP address of 10.10.20.30 to the
ExtremeCloud IQ - Site Engine database.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -add -oper
nsdevice -properties "ip=10.10.20.30,profileName=public_v1_
Profile,snmpContext=Switch,nickName=My Device"
Delete Operations
The -del, -oper, and -properties options are all required. The -oper option requires the nsdevice
value.
The only -properties option is the ip option (the device’s IP address) which is required.
For example, the following command deletes a device with the IP address of 10.10.20.30 from
the ExtremeCloud IQ - Site Engine database.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -del -oper
nsdevice -properties "ip=10.10.20.30"
Update Operations
The -update, -oper, and -properties options are all required. The -oper option requires the
nsdevice value.
The -properties option is a comma-separated list that can include the following values:
l ip - (required) the device's IP address.
l profileName - the profile assigned to the device.
l snmpContext - the SNMP context assigned to the device. An SNMP context is a collection of MIB
objects, often associated with an entity. By specifying the SNMP context, access is allowed to the subset
of MIB objects related to that context on the device.
l nickName - the nickname assigned to the device.
l userData1- optional customer-defined data.
l userData2- optional customer-defined data.
NAC Request Tool Operations
19 of 28
l userData3- optional customer-defined data.
l userData4- optional customer-defined data.
For example, the following command updates a device with the IP address of 10.10.20.30.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -update -oper
nsdevice -properties "ip=10.10.20.30,profileName=public_v1_
Profile,snmpContext=Switch,nickName=My.Device,userData1=data1,
userData2=data2,userData3=data3,userData4=data4"
Import or Export Devices in ExtremeCloud IQ - Site Engine
This request can be used to import a list of ExtremeCloud IQ - Site Engine devices using a text
file created in ExtremeCloud IQ - Site Engine Generated Format (.ngf file) or export a device list
from ExtremeCloud IQ - Site Engine to a text file created in ExtremeCloud IQ - Site Engine
Generated Format. For more information on ExtremeCloud IQ - Site Engine Generated Format
files, see the How to Export and Import a Device List help topic in your ExtremeCloud IQ - Site
Engine online help system.
Import Operations
The -import and -oper options are required. The -import option requires the path to the file to
import. The -oper option requires the nsdevice value. The imported file must be in the
ExtremeCloud IQ - Site Engine Generated Format (.ngf file).
For example, the following command imports a .ngf file called MyDevices.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -import
C:\Users\User\MyDevices.ngf -oper nsdevice
Export Operations
The -export and -oper options are required. The -export option requires the path to where the
file should be saved. The -oper option requires the nsdevice value. The exported file is saved in
the ExtremeCloud IQ - Site Engine Generated Format (.ngf file).
For example, the following command exports a .ngf file called MyDevices.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -export
C:\Users\User\MyDevices.ngf -oper nsdevice
Add or Update a Profile in ExtremeCloud IQ - Site Engine
This request adds or updates an ExtremeCloud IQ - Site Engine profile in the ExtremeCloud IQ -
Site Engine database. Profiles are used to manage access to your devices. For more information,
see the How to Configure Profiles and Credentials help topic in your ExtremeCloud IQ - Site
Engine online help system.
NAC Request Tool Operations
20 of 28
Add Operations
The -add, -oper, and -properties options are all required. The -oper option requires the nsprofile
value.
The -properties option is a comma-separated list that must include the following values:
l name - (required) the name of the profile.
l snmpVersion - (required for Add operations only) the SNMP protocol version for the profile: SNMPv1 (1),
SNMPv2c (2), or SNMPv3 (3).
l read/write/maxAccess - (required) When the version is SNMPv1 or SNMPv2c, the read, write, and
maxAccess properties specify the community name for each access level. When the version is SNMPv3,
the read, write, and maxAccess properties are the credentials specified for each access level.
l authCred - (required) the CLI Credential for this profile. CLI credentials provide support for device
management using the command line interface (CLI).
For example, the following command will add an SNMPv1 profile named My Profile to the
ExtremeCloud IQ - Site Engine database.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -add -oper
nsprofile -properties "name=My Profile,snmpVersion=1,read=public_
v1,write=public_v1,maxAccess=public_v1,authCred=Default"
In this example, the following command will add an SNMPv3 profile named My Profile to the
ExtremeCloud IQ - Site Engine database.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -add -oper
nsprofile -properties "name=My Profile,snmpVersion=3,read=default_snmp_
v3,write=default_snmp_v3,maxAccess=default_snmp_v3,authCred=Default"
Update Operations
The -update, -oper, and -properties options are all required. The -oper option requires the
nsprofile value. The -properties option is a comma-separated list that must include the following
values:
l name - (required) the name of the profile.
l read/write/maxAccess - (required) When the version is SNMPv1 or SNMPv2c, the read, write, and
maxAccess properties specify the community name for each access level. When the version is SNMPv3,
the read, write, and maxAccess properties are the credentials specified for each access level.
l authCred - (required) the CLI Credential for this profile. CLI credentials provide support for device
management using the command line interface (CLI).
For example, the following command will update an SNMPv1 profile named My Profile in the
ExtremeCloud IQ - Site Engine database.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -update -oper
nsprofile -properties "name=My Profile,read=public_v1,write=public_
v1,maxAccess=public_v1,authCred=Default"
NAC Request Tool Operations
21 of 28
In this example, the following command will update an SNMPv3 profile named My Profile in the
ExtremeCloud IQ - Site Engine database.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -update -oper
nsprofile -properties "name=My Profile,read=default_snmp_v3,write=default_
snmp_v3,maxAccess=default_snmp_v3,authCred=Default"
Add or Update a Credential in ExtremeCloud IQ - Site Engine
This request adds or updates an ExtremeCloud IQ - Site Engine credential in the ExtremeCloud
IQ - Site Engine database. Credentials are used to manage access to your devices. For more
information, see the How to Configure Profiles and Credentials help topic in your ExtremeCloud
IQ - Site Engine online help system.
Add Operations
The -add, -oper, and -properties options are all required. The -oper option requires the
nscredential value.
The -properties option is a comma-separated list that can include the following values:
l name - (required) the name of the credential.
l snmpVersion - (required) the SNMP protocol version for the credential: SNMPv1 (1), SNMPv2c (2), or
SNMPv3 (3).
l communityName - (required) for SNMPv1 or SNMPv2c credentials, this is the community name used for
device access.
l userName - (required) for SNMPv3 credentials, this is the User Name used for device access.
l authPassword - for SNMPv3 credentials, the password that is used to determine authentication.
l authType - for SNMPv3 credentials, the authType is MD5, SHA1, or None.
l privPassword - for SNMPv3 credentials, the password that is used to determine privacy.
l privType - for SNMPv3 credentials, the privType is DES, AES, or None.
For example, the following command will add an SNMPv1 credential named My Credential to the
ExtremeCloud IQ - Site Engine database.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -add -oper
nscredential -properties "name=My Credential,snmpVersion=1,communityName=some
name"
In this example, the following command adds an SNMPv3 credential named My Credential to the
ExtremeCloud IQ - Site Engine database.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -add -oper
nscredential -properties "name=My
Credential,snmpVersion=3,userName=admin,authPassword=pass,authType=SHA1,privP
assword=pass,privType=DES"
NAC Request Tool Operations
22 of 28
Update Operations
The -update, -oper, and -properties options are all required. The -oper option requires the
nscredential value.
The -properties option is a comma-separated list that can include the following values:
l name - (required) the name of the credential.
l communityName - (required) for SNMPv1 or SNMPv2c credentials, this is the community name used for
device access.
l userName - (required) for SNMPv3 credentials, this is the User Name used for device access.
l authPassword - for SNMPv3 credentials, the password that is used to determine authentication.
l authType - for SNMPv3 credentials, the authType is MD5, SHA1, or None.
l privPassword - for SNMPv3 credentials, the password that is used to determine privacy.
l privType - for SNMPv3 credentials, the privType is DES, AES, or None.
For example, the following command updates an SNMPv1 credential named My Credential in the
ExtremeCloud IQ - Site Engine database.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -update -oper
nscredential -properties "name=My Credential,communityName=some name"
In the next example, the command updates an SNMPv3 credential named My Credential in the
ExtremeCloud IQ - Site Engine database.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -update -oper
nscredential -properties "name=My
Credential,userName=admin,authPassword=pass,authType=SHA1,privPassword=pass,p
rivType=DES"
Add or Update a CLI Credential in ExtremeCloud IQ - Site Engine
This request adds or updates a CLI credential in the ExtremeCloud IQ - Site Engine database.
Credentials are used to manage access to your devices. For more information, see the How to
Configure Profiles and Credentials help topic in your ExtremeCloud IQ - Site Engine online help
system.
Add Operations
The -add, -oper, and -properties options are all required. The -oper option requires the
clicredential value.
The -properties option is a comma-separated list that must include the following values:
l userName - (required) the user name used for device access.
l description - (required) a description of the CLI credential.
l loginPassword - (required) the password required to start a CLI session.
NAC Request Tool Operations
23 of 28
l enablePassword - (required) the password for entering Enable mode.
l configurationPassword - (required) the password for entering Configure mode.
l type - (required) The communication protocol used for the connection (SSH or Telnet).
For example, the following command will add a CLI credential for a group of switches to the
ExtremeCloud IQ - Site Engine database.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -add -oper
clicredential -properties "userName=admin,description=East Wing
Switches,loginPassword=abc123, enablePassword=abc123,
configurationPassword=abc123, type=SSH"
Update Operations
The -update, -oper, and -properties options are all required. The -oper option requires the
clicredential value.
The -properties option is a comma-separated list that can include the following values:
l userName - (required) the user name used for device access.
l description - (required) a description of the CLI credential.
l loginPassword - the password required to start a CLI session.
l enablePassword - the password for entering Enable mode.
l configurationPassword - the password for entering Configure mode.
l type - the communication protocol used for the connection (SSH or Telnet).
For example, the following command will update the loginPassword in a CLI credential for a
group of switches.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -update -oper
clicredential -properties "userName=admin,description=East Wing
Switches,loginPassword=updatedPassabc123"
Update the NAC Request Tool Truststore
If you change the ExtremeCloud IQ - Site Engine server certificate, the NAC Request Tool can
no longer connect to the ExtremeCloud IQ - Site Engine server. This operation configures the
NAC Request Tool to trust the ExtremeCloud IQ - Site Engine server’s certificate, and enable
you to continue to use the NAC Request Tool.
The -oper option is required and uses the acceptcert value.
For example, the following command updates the local NAC Request Tool Truststore with the
ExtremeCloud IQ - Site Engine server certificate.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -oper acceptcert
Using a CSV File
24 of 28
Display Version Information
Use the following commands to display the NAC Request Tool version information.
./NacRequest.sh -version
Use the Timeout Option
This option enables you specify a time in milliseconds before the request is terminated. For
example, the following command includes a timeout value of 10 seconds (10000 milliseconds)
for an end-system information request.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -timeout 10000 -
oper info -endsystem 00:11:FB:55:55:61
Using a CSV File
A CSV file can be used to run multiple commands of the same operation type using the -csv
option. For example, multiple MAC addresses can be added to end-system groups, multiple
users can be added to user groups, or multiple end-systems can be reauthenticated. However,
multiple operations of different types cannot be combined in one CSV file, and the info
operation cannot be run using the -csv option.
NOTES: If a CSV file operation errors out, none of the entries in the file will be processed and added to the
ExtremeCloud IQ - Site Engine server.
End-systems assigned to one or more existing end-system groups being added to a new end-system
group using the –add option when importing using a CSV file remain a member of the
ExtremeControl end-system groups to which they are already assigned.
For example, the following command will send the contents of the CSV file "nacreq.csv" to NAC
Manager to be processed in one add end-system override operation.
NacRequest -server 10.20.33.2 -username admin -password pswd1 -add -oper
esoverride -csv nacreq.csv
CSV File Formats
Following are examples of possible CSV file formats.
Add or Delete End-System Override Operations
You can add or delete end-systems using a full MAC address, IP address, or hostname. If you are
using IP address or hostname, you must include the -type option in the command line (e.g. -type
"FULL_IP" or -type "HOSTNAME").
#macAddress, end-system group, description
00:90:BF:55:55:58, PrinterList, north side printer
Using a CSV File
25 of 28
00:90:BF:55:55:59, PrinterList, south side printer
00:90:BF:55:55:60, Registered Devices, user-xp1
#ipAddress, end-system group, description
10.20.30.40, PrinterList, north side printer
11.22.33.44, PrinterList, south side printer
12.23.34.44, Registered Devices, user-xp1
#hostname, end-system group, description
North Printer, PrinterList, north side printer
South Printer, PrinterList, south side printer
User-xp1, Registered Devices, 12.23.34.44
When adding end-systems using the custom data fields, only MAC addresses can be specified.
#macAddress, end-system group, custom1, custom2, custom3, custom4
00:90:BF:55:55:57, PrinterList, North Campus, Math Building, Floor 1, South Side
00:90:BF:55:55:58, PrinterList, North Campus, Math Building, Floor 2, South Side
00:90:BF:55:55:59, PrinterList, North Campus, Math Building, Floor 2, North Side
For a delete operation, the description is optional.
#macAddress, end-system group
00:90:BF:55:55:58, PrinterList
00:90:BF:55:55:59, PrinterList
For an add end-system to group and reauthenticate operation or a delete end-system from
group and reauthenticate operation, you must use a MAC address. The description is optional.
#macAddress, end-system group
00:90:BF:55:55:58, PrinterList
00:90:BF:55:55:59, PrinterList
Add or Delete User Override Operations
For both add and delete operations, the description is optional.
#username, user group, description
rjones, registereduser, enterprise user
tsmith, guest, guest user
Add, Update, or Delete Registered Users Operations
#properties
applianceGroup=default,userName=rjones,firstName=Ron,lastName=Jones
applianceGroup=default,userName=tsmith,firstName=Tom,lastName=Smith
For delete operations, only the applianceGroup and userName properties are required.
#properties
applianceGroup=default,userName=rjones
applianceGroup=default,userName=tsmith
Logging
26 of 28
Add, Update, or Delete Registered Devices Operations
#properties
applianceGroup=default,userName=rjones,macAddress=00:00:00:00:00:01,stateStr=Approved
applianceGroup=default,userName=tsmith,macAddress=00:00:00:00:00:02,stateStr=Approve
d
Reauthentication Operation
For a reauthentication operation, only MAC addresses can be specified.
#macAddress
00:90:BF:55:55:58
00:90:BF:55:55:59
Reauthentication and Scan Operation
For a reauthentication and scan operation, only MAC addresses can be specified.
#macAddress
00:90:BF:55:55:58
00:90:BF:55:55:59
Logging
The NAC Request Tool uses log4j as its logging utility and any output is automatically placed in
a log4j file in the location specified in the log4j.properties file. You must put the log4j.properties
file in the directory where you installed the NAC Request Tool.
Return Codes
Following the completion of a command, the NAC Request Tool returns a code indicating that
the operation was successful or that an error occurred during the operation. Detailed error
information will be included with the code, if available. Following is a list of possible return codes
and their meaning.
Return Codes
Return Code Description
0 The command was successful.
1 The requested object does not exist.
2 The action cannot be performed because the object already exists.
3 A parameter value is invalid.
4 An error occurred parsing an input string.
5 The result would be an invalid configuration.
6 Indicates an error using a remote connection.
Getting Help
27 of 28
Return Code Description
7 Indicates an unexpected error condition.
8 The group parameter object does not exist.
9 Indicates a generic CSV operation error occurred.
246 Indicates an authorization failure.
247 Indicates there was no response from the Web Service.
248 The request timed out.
249 The connection was reset.
250 The connection was refused.
251 Indicates a generic command line error.
252 The NAC Request Tool could not get a reference to the Web Service.
253 The IP address of the ExtremeCloud IQ - Site Engine Server is required,
but was not provided.
254 The user’s ExtremeCloud IQ - Site Engine username is required, but was
not provided.
255 The user’s ExtremeCloud IQ - Site Engine password is required, but was
not provided.
Getting Help
If you require assistance, contact Extreme Networks Global Technical Assistance Center using
one of the following methods.
Web www.extremenetworks.com/support/
Phone 1-800-872-8440 (toll-free in U.S. and Canada) or 1-603-952-5000
For the Extreme Networks Support phone number in your country:
www.extremenetworks.com/support/contact/
Email su[email protected]
Notice
Copyright © 2022 Extreme Networks, Inc. All Rights Reserved.
Legal Notices
Extreme Networks, Inc., on behalf of or through its wholly-owned subsidiary, Enterasys
Networks, Inc., reserves the right to make changes in specifications and other information
contained in this document and its website without prior notice. The reader should in all cases
consult representatives of Extreme Networks to determine whether any such changes have
been made.
Notice
28 of 28
The hardware, firmware, software or any specifications described or referred to in this
document are subject to change without notice.
Trademarks
Extreme Networks and the Extreme Networks logo are trademarks or registered trademarks of
Extreme Networks, Inc. in the United States and/or other countries.
All other names (including any product names) mentioned in this document are the property of
their respective owners and may be trademarks or registered trademarks of their respective
companies/owners.
For additional information on Extreme Networks trademarks, see:
www.extremenetworks.com/company/legal/trademarks/
Support
For product support, including documentation, visit: www.extremenetworks.com/support/
Contact
Extreme Networks, Inc.,
6480 Via Del Oro
San Jose, CA 95119
Tel: +1 408-579-2800
Toll-free: +1 888-257-3000
07/2022
22.06.10
PN: 9037534-00
Subject to Change Without Notice
