.\" fsports.4: auto-generated, DO NOT EDIT
.\"
.\" Copyright 2003-2019. Quantum Corporation. All Rights Reserved.
.\" StorNext is either a trademark or registered trademark of
.\" Quantum Corporation in the US and/or other countries.
.\"
.\" Code start macro
.de Cs
.ft C
.in +0.3i
.nf
..
.\" Code end macro
.de Ce
.fi
.in -0.3i
.ft R
..
.TH FSPORTS 4 "March 2019" "Xsan File System"
.SH NAME
fsports \- Xsan File System Port Restrictions
.SH SYNOPSIS
.na
.nh
.HP
.B /Library/Preferences/Xsan/fsports
.ad
.hy
.SH DESCRIPTION
The Xsan File System
\fBfsports\fR file 
provides a way to constrain the TCP and UDP
ports used by core Xsan server processes consisting of
the FSMs, the FSMPM, and any Distributed LAN servers.
This file can also be used to redefine the port used by the Xsan
Alternate Portmapper service.
The \fBfsports\fR file is usually only necessary when the Xsan control-network
configuration must pass through a firewall.
Use of the \fBfsports\fR file permits firewall pinholing
for improved security.
If no \fBfsports\fR file is used then port assignment is
operating-system dependent.
.SH SYNTAX
When an \fBfsports\fR file exists in the Xsan 'config' directory, it
restricts the TCP and UDP port bindings to the user-specified range.
The format of the \fBfsports\fR file has two required lines,
one optional line, and comments starting with pound-sign (#) in column one
as follows:
.Cs
MinPort \fIvalue\fP
MaxPort \fIvalue\fP
AltPmap \fIvalue\fP
.Ce
.PP
The \fIvalue\fR fields are port numbers that define
an inclusive range of ports that the Xsan server processes can use.
Be careful to choose port range values that are appropriate for your
operating system. Note that the Internet Assigned Numbers Authority
(IANA) suggests a dynamic client port range for outgoing connections
of 49152 through 65535. With that in mind, most Linux kernels use a port
range of 32768 through 61000, Microsoft Windows operating systems through
XP use the range 1025 to 5000 by default, Windows Vista, Windows 7, and
Server 2008 use the IANA range by default, and Windows Server 2003 uses the
range 1025 to 5000 by default, until Microsoft security update MS08-037
from 2008 is installed, after which it uses the IANA range by default.
.PP
The optional \fBAltPmap\fR value changes the TCP port used for the Xsan Alternate
Portmapper service, which defaults to port 5164.  
When Xsan is used with a firewall, you can either configure the firewall to 
allow port 5164 or change the SNFS port number via the \fBAltPmap\fR keyword 
to a port that is allowed to pass through the firewall.  
.PP
The \fBAltPmap\fR value must be defined the same way on all Xsan server and 
client nodes in order for Xsan to function properly.  
When using \fBAltPmap\fR to change the Xsan Alternate Portmapper 
service port number, you must include an fsports file on every Xsan client 
and server with the same \fBAltPmap\fR value.  When the \fBAltPmap\fR keyword is not 
used, the \fBfsports\fR file is not necessary on Xsan clients.
.PP
The minimum number of ports needed on a given node can be computed as follows:
one port for the FsmPm process, plus one port for each FSM process, plus one
port for each file system served by this node as a Distributed LAN server.
.SH EXAMPLE
To restrict Xsan Server processes to using ports 52,000 through 52,100 the
\fBfsports\fR file would contain the following lines:
.Cs
MinPort 52000
MaxPort 52100
.Ce
.PP
This \fBfsports\fR file is only needed on Xsan servers.
.PP
To restrict Xsan Alternate Portmapper service to a specific port, select
a port number outside the range of the \fBMinPort\fR and \fBMaxPort\fR values.   For 
example if \fBMinPort\fR is 52000 and \fBMaxPort\fR is 52100 then select a value
outside that range.
.Cs
MinPort 52000
MaxPort 52100
AltPmap 52101
.Ce
.PP
This \fBfsports\fR file is required on all Xsan clients and servers.
.SH COMMON FSPORTS COOKBOOK
The primary use case for fsports is allowing StorNext SAN and LAN clients
outside of a firewall to access the services provided by StorNext servers
inside of a firewall.  While other use cases exist, and more complex
and restrictive configurations are possible, the following "cookbook"
steps describe how to produce a common fsports file for all servers
inside of a firewall.  The resultant file provides security without 
sacrificing ease of deployment.
.IP "\fBStep 1.\fR" 0
Determine the set of servers inside of the firewall that need to be
accessed.  This may include primary and standby MDCs and 
Distributed LAN servers.
.IP "\fBStep 2.\fR" 0
For the list of servers from Step 1, determine the maximum
number of StorNext ports used by any one server.  The following equation
can be used for this calculation:
.RS 2n
.TP 4n
# ports required for a given server = (
Three ports for each file system in the "fsmlist" file +
.br
One port for each file system for which this server is acting as a Distributed LAN server +
.br
Two ports for the Tiering, if enabled +
.br
Three ports for the Alternate Portmapper, the NSS protocol, and fsmpm web services ) * \fIMultiplier\fR
.RE
.PP
where \fIMultiplier\fR is 2 for Windows servers and 1 for non-Windows servers.
.PP
For example, consider the following configuration of servers inside
of a firewall that need to be accessed by clients outside of the
firewall:
.RS 2n
.TP 4n
A Linux MDC hosting 4 file systems and Tiering enabled
ports: (4 * 3 + 0 + 2 + 3) * 1  =  17
.TP 4n
A second Linux MDC hosting 6 file systems
ports: (6 * 3 + 0 + 0 + 3) * 1  =  21
.TP 4n
A Windows MDC hosting 1 file system and acting as a Distributed LAN server for just that file system
ports: (1 * 3 + 1 + 0 + 3) * 2  =  14
.TP 4n
A dedicated Linux Distributed LAN server that serves 9 file systems from the various MDC pairs
ports: (0 + 9 + 0 + 3) * 1  = 12
.TP 4n
The maximum number of StorNext ports needed by any one server is:
MAX(17, 21, 14, 12) = 21 ports
.RE
.IP "\fBStep 3.\fR" 0
Based on the maximum port count determined in step 2, pick
a range of unused ports on the firewall and open them up.  For example,
for a maximum port count of 21, ports 52000 through 52020 could be chosen
if they are available.  The firewall should be configured to allow
outside UDP and TCP connections using any source port to connect to 
StorNext servers inside the firewall having the restricted range of 
ports.  Port 5164 should also be opened up for TCP for the 
AltPortMap service.  (See NOTES below if this is not possible.)
.IP "\fBStep 4.\fR" 0
Configure the common fsports file.  Using the example from
step 3 of where 10 ports are needed starting at 52000.
The configuration is as follows:
.Cs
MinPort 52000
MaxPort 52020
.Ce
.IP "\fBStep 5.\fR" 0
Install the resulting file on all servers from Step 1.  Also install 
the file on all clients if the \fBAltPmap\fR directive was used.
Then restart StorNext.
.SH NOTES
Servers having common fsports files will use the same range of
network ports for core StorNext file system services.  This does not 
result in conflicts since each network address is comprised of an IP 
address and a port number and is therefore unique even when 
using the same port number as another network address.
.PP
As mentioned under EXAMPLES, when port 5164 cannot be opened on the 
firewall for the AltPortMap service, it is possible to use the \fBAltPmap\fR
directive in the fsports file so that a different port is used.  This
also requires that clients outside of the firewall use an fsports file.
.PP
The fsports file does not constrain the ports used by the client end of 
connections.  Ephemeral ports are used instead.  Therefore, the fsports 
file is only useful on clients when the \fBAltPmap\fR directive is used.
.PP
When using fsports files, if services fail to start or clients fail
to connect, to debug the problem, try slightly increasing the range of 
open StorNext ports on the firewall and, correspondingly, in the fsports 
files.  Running netstat on the servers may reveal that unexpected processes 
are binding to ports within the range specified in the fsports file.
Also, if services are restarted on Windows servers, in some cases
ports may not be reusable for several minutes.  Using an expanded port
range will work around this.
.PP
The information above covers the ports used by the core StorNext file 
system services.  If firewall pinholing is needed for other StorNext 
services (for example, replication), additional hard-wired ports may 
need to be opened on the firewall outside of the domain of the fsports 
file.  Refer to the "Port Used by StorNext" section in the StorNext 
File System Tuning Guide.
.SH UPDATING FSPORTS CONFIGURATION ON AN HA PAIR
.PP
When changing the fsports configuration on an HA pair and the
\fBAltPmap\fR directive is used, special care must be taken
to avoid having the HA mechanism reboot one or both of the
HA nodes. Here is the sequence to follow:
.IP "\fBStep 1.\fR" 0
Use the StorNext GUI to enter HA config mode. This locks the secondary
node and allows configuration changes to be made on the primary node.
.IP "\fBStep 2.\fR" 0
Stop the cvfs service on the primary node.
.IP "\fBStep 3.\fR" 0
Stop the cvfs service on the coordinator (name service) nodes.
.IP "\fBStep 4.\fR" 0
Update, remove or create the fsports file on the coordinator nodes.
.IP "\fBStep 5.\fR" 0
Start the cvfs service on the coordinator nodes.
.IP "\fBStep 6.\fR" 0
Update, remove or create the fsports file on both the
HA primary and HA secondary nodes.
.IP "\fBStep 7.\fR" 0
Start the cvfs service on the primary node.
.IP "\fBStep 8.\fR" 0
Use the StorNext GUI to exit HA config mode.
.PP
If not using external coordinators, that is, the HA MDC pair
are the coordinators for the cluster, eliminate steps 3, 4 and 5.
.SH FILES
.I /Library/Preferences/Xsan/fsports
.br
.I /System/Library/Filesystems/acfs.fs/Contents/examples/fsports.example
.SH "SEE ALSO"
.BR cvfs (8),
.BR snfs_config (5),
.BR fsm (8),
.BR fsmpm (8)