Commit d3581895 authored by Alexander Detsch's avatar Alexander Detsch 🐘
Browse files

added manpage

parent 11b8e27d
.TH ADD-ARUBA-AP 1 2021-03-12 GNU "FeM manual"
.SH NAME
add-aruba-ap \- Script to register Aruba APs in the FeM infrastructure
.SH SYNOPSIS
.B add_aruba_ap.py
.RB [ Options... ]
.SH DESCRIPTION
.B add-aruba-ap
registers Aruba access points in the AdminDB and Aruba Mobility Masters.
It further adds the registered Access Points to Netbox via a Netbox script and
updates location information in the Wiki.
The access point's configuration is passed entirely via command line parameters or via a CSV table.
.PP
.B add-aruba-ap
informs about unset required parameters or missing modules on the command line before performing any actions.
Errors occuring during the execution result in immediate abortion of the current access point's configuration tasks, possibly having just parts of the script's task executed.
One can use the appropriate command line options to execute only the tasks which have failed before.
.PP
During execution, information about any occured error is given.
.PP
.B add-aruba-ap
provides a so-called batch-mode.
In this mode, access point configuration is passed via a csv file containing configuration parameters for multiple access points.
Errors during the configuration of a single access point doesn't affect the remaining tasks, but rather aborts the configuration of only the failed access point and outputs the error messages.
Afterwards, all failed tasks are listed in the order of execution.
.SH OPTIONS
.TP
.BR -h | --help
Print the help message and exit.
.TP
.BR --skipadmindb
Skip adding the Aruba AP to the AdminDB.
This option should be used if an already registered AP is being reused
(e.g. if the AP has been de-provisioned in the Mobility Master, but not de-registered in the AdminDB).
.TP
.B --host \c
.I host-name
Connect to the AdminDB at the host
.IR host-name .
This is optional and, when unset, the script connects to the default AdminDB host.
.TP
.B --port \c
.I port-number
Connect to the AdminDB at the port
.IR port-number .
This is optional and, when unset, the script connects to the default PostgreSQL port.
.TP
.B --dbname \c
.I database-name
Work with database
.I database-name
in the AdminDB.
This is optional and, when unset, uses the default AdminDB database name.
.TP
.B --memberid \c
.I member-id
Register the access point for the member with the ID
.I member-id
in the AdminDB.
This is optional and, when unset, uses the default AdminDB FeM user.
.TP
.BR --user , -u \c
.I " user-name"
Specifies the user name to use for authenticating against the AdminDB.
This should be the AdminDB account user name of the admin who registers the access point.
.TP
.BR --password , -p \c
.I " password"
Specifies the password to use for authenticating against the AdminDB.
If it is not desired to set the password as plain text argument,
the option can be left unspecified to make the script prompt for the password interactively.
.TP
.B --vlan \c
.I VLAN
Register the access point with an IP address from the subnet belonging to the given
.I VLAN
and set
.I VLAN
as VLAN to use for automatic switch port configuration.
This is optional and, when uset, uses the default Aruba AP VLAN which is used in the FeM-Net.
.TP
.B --mac \c
.I MAC-address
Register the access point with the given MAC address.
This option applies to all configuration steps.
.TP
.B --name \c
.I name
Register the access point with the given
.IR name .
This option applies to all configuration steps.
It is further required for the proper mapping of the access point to it's location for monitoring and similar purposes.
See
.I Access point names and numbers
for information about the naming scheme.
If the access point name does not have the prefix
.BR aruba-ap- ,
the prefix will be added automatically except if
.B --skipprefix
is set.
.TP
.B --skipprefix
When creating an access point with a name which has no prefix
.BR aruba-ap- ,
don't add the prefix automatically.
This option might come in handy in the future, but has no real use as of writing this manpage.
.TP
.B --mmwhitelist
Enable whitelisting the access point in the Aruba mobility master.
If this option is unset, no interaction with the mobility master happens and thus the access point needs to be provisioned manually after starting the access point for the first time.
Any parameters which are only used during mobility-master-related tasks are ignored.
.TP
.B --mmuser \c
.I user-name
Authenticate as user
.I user-name
when connecting to the mobility master.
This is usually the user
.BR fem .
.TP
.B --mmpass \c
.I password
Authenticate with the
.I password
when connecting to the mobility master.
The
.B fem
user uses the current FeM switch password as password.
Please ask a fellow FeM technician if the switch password is unknown to you.
If the password is not provided as command-line parameter, it will be asked for interactively before executing the first task
.TP
.B --mmurl \c
.I URL
Connect to the mobility master at
.IR URL .
If unset, the default FeM mobility master URL is being used.
.TP
.B --mmgroup \c
.I group
Configure the access point to be assigned to the
.I group
when provisioning the access point automatically.
If unset, the default FeM access point group
.B fem-ap-group
is being used.
See
.I Aruba access point groups
for details on which access point group to use in which situation.
.TP
.B --mmproxy \c
.I proxy-URL
Use the proxy at
.I proxy-URL
when connecting to the mobility master.
As the FeM Aruba mobility master is only reachable from within the management network,
a proxy might be neccessary in most cases to establish a connection to the mobility master.
See
.I Proxy URLs
for the right syntax to specify proxy URLs.
.TP
.B --mmverify
Enable verification of SSL certificates when connecting to the mobility master.
This option is disabled by default as FeM's mobility master is inside the management network which is not reachable from general networks.
.TP
.B --skipnetbox
Disable adding the access point in Netbox.
If set, any options only related to Netbox will be ignored.
.TP
.B --nbapiurl \c
.I URL
Connect to the Netbox instance at
.IR URL .
This is optional and, when unset, the script connects to FeM's Netbox server.
.TP
.B --nbapikey \c
.I key
Use the
.I key
as token to connect to the Netbox API.
The key has to be created in the Netbox web frontend before executing the script.
.TP
.B --type \c
.I ap-type
Set the AP type to
.I ap-type
in Netbox.
The AP type is provided as slug due to the fact that AP type labels might change more frequently in Netbox.
Usually, this is one of
.BR ap-205h ", " ap-303 ", and " iap-315 .
.TP
.B --ip \c
.I IP-address
This option is deprecated and setting it has no effects.
In earlier versions, the access point's IP address had to be set with this option to add the access point to Netbox.
.TP
.B --skipwiki
Do not update the access point information in the wiki.
.TP
.B --wikiuser \c
.I user-name
Authenticate against the wiki as
.IR user-name .
Usually, this will be the LDAP credentials.
.TP
.B --wikipassword \c
.I password
Authenticate against the wiki with
.IR password .
Usually, this will be the LDAP credentials.
.TP
.B --wikiurl \c
.I URL
Connect to the wiki at
.IR URL .
This parameter is optional and uses the FeM wiki's URL per default.
.TP
.B --location \c
.I location
Enter the human readable
.I location
as access point location in the wiki.
See
.I Location names
for conventions on location naming.
.TP
.BR --pretend | -P
Do not actually do any permanent changes, but do a dry-run instead.
This option does
.B not
support MM registration.
.TP
.BR --batch | -b \c
.I " csv-file"
Configure access points in batch-mode using the information provided in
.IR csv-file .
See
.I Batch-mode configuration
for information on the file layout.
.SH EXIT STATUS
On success,
.B 0
is returned;
on failure,
.B 1
is returend.
.SH NOTES
.SS Access point names and numbers
Names usually have the form
.PP
.in +4n
.EX
.BR aruba-ap- [ \c
.IR block ][ number ]
.EE
.in
.PP
where
.I block
is the lowercase short name of the block or location of the access point (e.g.
.BR e ", " cjd ", " fahrradwerkstatt )
and
.I number
is the access point's number within the location, following a numbering scheme usually consisting of a consecutive numbering starting at some place in the building.
Please consult the FeM Wiki's
.UR https://wiki.fem.tu-ilmenau.de/technik/wlan/aruba-wlan/haeuser
.UE WLAN access point plan
for the required numbering scheme.
.SS Access point groups
.TP
.B default
This is the default access point group of the mobility master and is
.I not used
when working with FeM access points.
However, it is initially assigned when an access points is being initially provisioned without prior whitelisting.
.TP
.B fem-ap-group
This is the main access point group used for FeM access points.
This group makes access points provide the regular FeM networks and shall be used when registering access points in houses which have mainly Aruba WLAN deployed or no WLAN at all.
.TP
.B fem-ap-group-ng
This is the secondary access point group used for FeM access points in houses which have some other WLAN system deployed as primary WLAN system.
Furthermore, this group is used in houses where the transition from another WLAN system to the Aruba WLAN system is in progress.
After such a transition, the access point shall be configured to be in the
.BR fem-ap-group .
.TP
Other access point groups
Any access point group not mentioned here shall not be used for general WLAN deployment.
.SS Proxy URLs
Proxy URLs are specified in the form
.PP
.in +4n
.EX
.RI [ protocol ]://[ host ]:[ port ]
.EE
.in
.PP
Usually, a SOCKS5 proxy is being used via SSH.
In that case, the proxy URL looks like this:
.PP
.in +4n
.EX
.BR socks5h :// localhost :[ \c
.IR port ]
.EE
.in
.SS Location names
Location names are human-readable and not meant to be read automatically.
Thus, there are no restrictions on the naming scheme.
It is, however, suggested to follow a few conventions for names:
.PP
.IP o
If room/dorm names are used, follow the naming scheme as used by the landlord or
as used inside the AdminDB internally.
.PP
.IP o
If APs are installed in corridors without any specific name (e.g. as it is the
case in house N), use a location description relative to the entrance (e.g.
.BR 3. OG, Flur links ).
.SS Batch-mode configuration
In batch-mode, the access points' configurations are passed via a csv file.
The file needs to satisfy the following properties:
.PP
.IP o
Columns are labeled with the first line of the file containing the column labels.
The columns
.BR ap-name ", " mac-address ", " serialnumber ", and " location
are required.
Further columns might be required in future versions.
The order of the columns is not important.
Their meaning should be self-explanatory and
follow the same conventions as their command-line parameter counterparts.
.IP o
Columns are separated with a single
.B ;
character.
Lines are separated using standard newline.
.SH EXAMPLE
.SS Registration via command-line
Assume, an access point with the MAC address
.I af:bf:cf:df:ef:ff
shall be installed in house
.I X
and has the number
.I 27
according to the numbering scheme and shall be installed in room
.BR 02-04-1 .
The access point's serial number is
.I DN12345678
and is of the type
.IR ap-205h .
The access point shall be registered in the access point group
.I fem-ap-group-ng
and the SOCKS5 proxy at
.I localhost:8080
is being used.
All credentials are passed via the command line.
The default AdminDB and mobility master is being used.
.TP
.in +4n
.EX
add_aruba_ap.py \\
--user nex \\
--password testtesttest \\
--mac af:bf:cf:df:ef:ff \\
--name aruba-ap-x27 \\
--mmwhitelist \\
--mmuser fem \\
--mmpass switchpass \\
--mmgroup fem-ap-group-ng \\
--mmproxy socks5h://localhost:8080 \\
--type ap-205h \\
--nbapikey mykey \\
--wikiuser nex \\
--wikipassword testtesttest \\
--location 02-04-1
.EE
.in
.SS Registration via batch-mode
To run the above example using batch-mode, a few adjustments are necessary.
.PP
First, a csv-file
.B ap-mapping.csv
is created with the following contents:
.PP
.in +4n
.EX
ap-name;mac-address;serialnumber;location
aruba-ap-x27;af:bf:cf:df:ef:ff;DN12345678;02-04-1
.EE
.in
.PP
Now, the command-line is as follows:
.TP
.in +4n
.EX
add_aruba_ap.py \\
--user nex \\
--password testtesttest \\
--mmwhitelist \\
--mmuser fem \\
--mmpass switchpass \\
--mmgroup fem-ap-group-ng \\
--mmproxy socks5h://localhost:8080 \\
--type ap-205h \\
--nbapikey mykey \\
--batch ap-mapping.csv
.EE
.in
.TH PREPARE-ARUBA-AP-SWITCHPORT 1 2021-02-24 "FeM manual"
.SH NAME
prepare-aruba-ap-switchport \- Script to configure switch ports as required for Aruba access points in dorms
.SH SYNOPSIS
.B prepare_aruba_ap_switchport.py
.RB [ Options... ]
.SH DESCRIPTION
.B prepare-aruba-ap-switchport
configures switch ports and user ports in the AdminDB in the way which is required for Aruba access points to be installed in the dorms of FeM members.
.PP
.B prepare-aruba-ap-switchport
sets the right switch port class, creates necessary virtual switch ports and user ports, moves the existing user port to the new virtual switchport and moves a newly created user port to the physical switch port.
.PP
Support for bulk actions and automatic lookup is provided if a csv file with the required mapping is provided.
.SH OPTIONS
.TP
.BR -h | --help
Print the help message and exit.
.TP
.B --host \c
.I host-name
Connect to the AdminDB at the host
.IR host-name .
This is optional and, when unset, the script connects to the defualt AdminDB host.
.TP
.B --port \c
.I port-number
Connect to the AdminDB at the port
.IR port-number .
This is optional and, when unset, the script connects to the default PostgreSQL port.
.TP
.B --dbname \c
.I database-name
Work with database
.I database-name
in the AdminDB.
This is optional and, when unset, uses the default AdminDB database name.
.TP
.BR -u | --user \c
.I " user-name"
Authenticate against the AdminDB as
.IR user-name .
.TP
.BR -p | --password \c
.I " password"
Authenticate against the AdminDB with the given
.IR password .
If this option is unset, the password will be asked for interactively.
.TP
.BR -n | --apname \c
.I " ap-name"
Register the access point with the name
.IR ap-name,
omitting the common prefix
.BR aruba-ap- .
.TP
.BR -s | --switchportid \c
.I " switch-port-id"
Configure the switch port with the ID
.IR switch-port-id .
In lookup-mode, this option will be ignored.
.TP
.B --wiredswitchid \c
.I switch-id
Configure the virtual switch port on the virtual switch with ID
.IR switch-id .
This is optional and, if unset, uses the default
.B arubawlanwired
switch.
.TP
.BR -l | --lookup \c
.I " lookup-file"
Enable lookup-mode using
.I lookup-file
as lookup table.
The file should be in CSV format with the columns
.I ap-name
and
.IR switchport-id .
Any additional columns are ignored.
Lookup-mode disables passing the switch port ID via
.BR --switchportid .
.SH EXIT STATUS
On success,
.B 0
is returned; on failure,
.B 1
is returned.
.SH NOTES
.SS Access point names and numbers
Names follow a convention similar to
.BR add-aruba-ap (1)
with the exception that the prefix
.B aruba-ap-
is omitted.
.SH EXAMPLE
.SS Preparation without lookup-mode
Assume, access point
.B aruba-ap-q27
should be connected to the switch port with ID
.BR 12345 .
To configure the ports, run:
.TP
.in +4n
.EX
prepare_aruba_ap_switchport.py \\
--user myname \\
--apname q27 \\
--switchportid 12345
.EN
.in
.SS Preparation with lookup-mode
Using the above example, but with lookup-mode, the switch port ID does not need to be passed as a command line parameter.
Instead, the lookup file
.B lookup.csv
will be passed:
.TP
.in +4n
.EX
prepare_aruba_ap_switchport.py \\
--user myname \\
--apname q27 \\
--lookup lookup.csv
.EN
.in
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment