Janus FTP Server: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(39 intermediate revisions by 2 users not shown)
Line 7: Line 7:
   
   
The FTP client may be running on any platform that can make a TCP/IP connection to the online.
The FTP client may be running on any platform that can make a TCP/IP connection to the online.
Many tools such as code management systems and editors have built in
Many tools such as code management systems and editors have built-in
FTP clients which can now be used with <var class="product">Model 204</var>
FTP clients which can now be used with <var class="product">Model 204</var>
procedures and procedure files.
procedures and procedure files.
Line 13: Line 13:
Janus FTP servers can peacefully coexist with any other FTP servers you may be running.
Janus FTP servers can peacefully coexist with any other FTP servers you may be running.
   
   
You must be licensed for <var class="product">Janus Sockets</var> and <var class="product">Janus TCP/IP Base</var> in order to use Janus FTP support.  
You must be licensed for <var class="product">[[Janus Sockets]]</var> and <var class="product">[[Janus TCP/IP Base]]</var> in order to use Janus FTP support.  
   
   
==Feature description==
This article provides an overview of the capabilities and features
This section provides an overview of the capabilities and features
of <var class="product">Janus FTP Server</var> support. The remaining topics that describe <var class="product">Janus FTP Server</var> support are referenced in the [[#See also|"See also"]] section at the bottom of the page.
of <var class="product">Janus FTP Server</var> support.
 
The section includes these topics:
The best place for detailed information about FTP is [http://www.ietf.org/rfc/rfc959.txt Internet RFC 959], which specifies the protocol. In addition, there are a number of open source FTP clients and servers that one may examine.
<ul>
They can be found using a search engine like <var class="product">Google</var>.
<li>[[#Feature summary|"Feature summary"]]
<li>[[#Key concepts|"Key concepts"]]
<li>[[#Command overview|"Command overview"]]
<li>[[#Socket and procedure handling|"Socket and procedure handling"]]
<li>[[#Security and Janus FTP Server|"Security and Janus FTP Server"]]
<li>[[#FTP features not currently supported|"FTP features not currently supported"]]
<li>[[#Supported FTP protocol commands|"Supported FTP protocol commands"]]
</ul>
   
   
===Feature summary===
==Feature summary==
The following capabilities are provided by the <var class="product">Janus FTP Server</var>.
The following capabilities are provided by the <var class="product">Janus FTP Server</var>.
<ul>
<ul>
<li><var class="product">Model 204</var> procedures may be downloaded to a local platform
<li><var class="product">Model 204</var> procedures may be downloaded to a local platform
using any FTP client.
using any FTP client.
<li><var class="product">Model 204</var> procedures may be added, replaced, deleted, and renamed with
<li><var class="product">Model 204</var> procedures may be added, replaced, deleted, and renamed with
any FTP client.
any FTP client.
<li>Procedure listings are supported (the FTP protocol <var>LIST</var> command).
 
This permits GUI FTP clients such as <var class="product">WS_FTP< and others to render lists
<li>'''Procedure listings''' are supported (the FTP protocol <var>LIST</var> command).
This permits GUI FTP clients such as <var class="product">WS_FTP</var> and others to render lists
of <var class="product">Model 204</var> procedures.
of <var class="product">Model 204</var> procedures.
<li>EBCDIC/ASCII translation in both directions is automatic and transparent for FTP ASCII text transfers.
 
<li>Binary file transfers (FTP <code>TYPE I</code> are supported to permit
<li>'''EBCDIC/ASCII translation''' in both directions is automatic and transparent for FTP ASCII text transfers.
 
<li>'''Binary file transfers''' (FTP <code>TYPE I</code> are supported to permit
transfer of binary files such as images (.JPG, .GIF, etc.) and Java applets (.class, .jar, etc.).
transfer of binary files such as images (.JPG, .GIF, etc.) and Java applets (.class, .jar, etc.).
<li><var>JANUS FTP</var> commands are used to map the
<li><var>JANUS FTP</var> commands are used to map the
standard UNIX folder structure that FTP clients expect to <var class="product">Model 204</var>
standard UNIX folder structure that FTP clients expect to <var class="product">Model 204</var>
Line 47: Line 44:
Multiple <var class="product">Model 204</var> procedure files may be accessed
Multiple <var class="product">Model 204</var> procedure files may be accessed
from a single port with a Janus FTP server.
from a single port with a Janus FTP server.
This mapping effectively creates folders that can be navigated by FTP clients
This mapping effectively creates '''folders that can be navigated by FTP clients'''
using the standard FTP <code>cwd</code> command (change working directory/folder).
using the standard FTP <code>cwd</code> command (change working directory/folder).
For more information, see [[#Folder mapping|"Folder mapping"]].
For more information, see [[#Folder mapping|"Folder mapping"]].
<li>FTP user authentication is based on <var class="product">Model 204</var> user IDs and passwords.
 
<li>FTP '''user authentication''' is based on <var class="product">Model 204</var> user IDs and passwords.
It automatically uses whatever security package (for example, RACF), that
It automatically uses whatever security package (for example, RACF), that
your online uses to authenticate logins.
your online uses to authenticate logins.
<li>Anonymous FTP is available.
 
<li>'''Anonymous FTP''' is available.
For security, anonymous FTP is off by default
For security, anonymous FTP is off by default
when an <var class="product">FTP Server</var> is created with <var>JANUS DEFINE</var>.
when an <var class="product">FTP Server</var> is created with <var>[[Janus FTP Server command reference#JANUS DEFINE for FTP|JANUS DEFINE]]</var>.
Extra syntax is required to enable anonymous FTP, which makes it impossible to accidentally
Extra syntax is required to enable anonymous FTP, which makes it impossible to accidentally
enable it when you are creating an FTP server.
enable it when you are creating an FTP server.
For more information, see [[#Anonymous FTP|"Anonymous FTP"]].
For more information, see [[#Anonymous FTP|"Anonymous FTP"]].
<li>Active and passive FTP are supported. Passive is more secure, and
 
<li>'''Active and passive FTP''' are supported. Passive is more secure, and
Sirius recommends using passive FTP where possible.
Sirius recommends using passive FTP where possible.
However, some older and simpler FTP clients only work with active FTP
However, some older and simpler FTP clients only work with active FTP
Line 67: Line 67:
to open up TCP/IP server sockets, which is commonly viewed as a security exposure,
to open up TCP/IP server sockets, which is commonly viewed as a security exposure,
thus prevented by many firewalls.
thus prevented by many firewalls.
<li>All three operating systems are supported (MVS, VM, and VSE).
 
<li>Within an online, you can run as many FTP servers as you want, using
<li>All '''three operating systems''' are supported (MVS, VM, and VSE).
 
<li>'''FTPS''' (SSL/TLS encrypted data transmission) is [[#Security and Janus FTP Server|available]] as of <var class="product">Sirius Mods</var> version 8.0.
 
<li>Within an Online, you can run '''as many FTP servers as you want''', using
different port numbers for each.
different port numbers for each.
There is no requirement to use the default FTP port number (21).
There is no requirement to use the default FTP port number (21).
Line 76: Line 80:
client software will have to be reconfigured otherwise.
client software will have to be reconfigured otherwise.
(By default, all FTP clients try to connect to port 21.)
(By default, all FTP clients try to connect to port 21.)
<li>For advanced applications, you can write "overrides" for FTP commands,
 
<li>For advanced applications, you can write '''"overrides" for FTP commands''',
where you provide a custom implementation for a command to perform application-specific processing.
where you provide a custom implementation for a command to perform application-specific processing.
Overrides are written in <var class="product">User Language</var>.
Overrides are written in <var class="product">User Language</var>.
A possible use of an override is to read and write records from a
A possible use of an override is to read and write records from a
<var class="product">Model 204</var> file using FTP.
<var class="product">Model 204</var> file using FTP.
For more information, see [[#Overriding FTP protocol commands|"Overriding FTP protocol commands"]].
For more information, see [[Overriding FTP protocol commands|"Overriding FTP protocol commands"]].
 
<li>You can use the procedure name suffix (for example, <code>.HTML</code>) to control the
<li>You can use the procedure name suffix (for example, <code>.HTML</code>) to control the
transfer mode of a file (text vs. binary).
transfer mode of a file (text vs. binary).
For more information, see <var>[[#JANUS FTP SUFFIX|JANUS FTP SUFFIX]]</var>.
For more information, see <var>[[Janus FTP Server command reference#JANUS FTP SUFFIX|JANUS FTP SUFFIX]]</var>.
</ul>
</ul>
 
===Key concepts===
==Key concepts==
This section covers the key concepts to master to use the <var class="product">Janus FTP Server</var>.
This section covers the key concepts to master to use the <var class="product">Janus FTP Server</var>.
It is vital to grasp these concepts before learning specific commands.
It is vital to grasp these concepts before learning specific commands.
   
   
====Folder mapping====
===Folder mapping===
The most important concept to understand when
The most important concept to understand when
using the <var class="product">Janus FTP Server</var> is the concept of folder mapping.
using the <var class="product">Janus FTP Server</var> is the concept of folder mapping.
Line 99: Line 105:
any concept of hierarchy.
any concept of hierarchy.
   
   
<var class="product">Janus FTP Server</var> provides a command (<var>[[#JANUS FTP ASSIGN|JANUS FTP ASSIGN]]</var>)
<var class="product">Janus FTP Server</var> provides a command (<var>[[Janus FTP Server command reference#JANUS FTP ASSIGN|JANUS FTP ASSIGN]]</var>)
that lets you create folders.
that lets you create folders.
Folders are referenced by an FTP client to locate procedures, which the FTP client sees as files.
Folders are referenced by an FTP client to locate procedures, which the FTP client sees as files.
Line 124: Line 130:
This permits the system manager to switch procedure files without breaking users' FTP client setups.
This permits the system manager to switch procedure files without breaking users' FTP client setups.
A user simply changes the folder mapping to point to the new procedure file.
A user simply changes the folder mapping to point to the new procedure file.
 
====Folder names====
===Folder names===
The names of FTP folders must obey the following syntax rules:
The names of FTP folders must obey the following syntax rules:
<ul>
<ul>
Line 144: Line 150:
</p>
</p>
   
   
====Prefixing====
===Prefixing===
By default, a folder mapping is simply a way to connect a folder seen by the
By default, a folder mapping is simply a way to connect a folder seen by the
FTP client to a <var class="product">Model 204</var> file.
FTP client to a <var class="product">Model 204</var> file.
Line 151: Line 157:
transparent to the FTP client.
transparent to the FTP client.
Prefixing is off by default, but it can
Prefixing is off by default, but it can
be enabled using the <var>PREFIX</var> parameter on the <var>[[#JANUS FTP ASSIGN]]</var> command.
be enabled using the <var>PREFIX</var> parameter on the <var>[[Janus FTP Server command reference#JANUS FTP ASSIGN|JANUS FTP ASSIGN]]</var> command.
   
   
Prefixing a folder has the characteristics listed below.
Prefixing a folder has the characteristics listed below.
Line 179: Line 185:
the FTP clients see only the slashes. </p>
the FTP clients see only the slashes. </p>
</ul>
</ul>
 
====Folder security====
===Folder security===
FTP folder access rights are granted to one or more users in
FTP folder access rights are granted to one or more users in
either of the following ways:
either of the following ways:
Line 187: Line 193:
for all users (not including anonymous access) may be assigned.
for all users (not including anonymous access) may be assigned.
<li>A user, user group, all users (except anonymous), or the anonymous user
<li>A user, user group, all users (except anonymous), or the anonymous user
may be given access rights to a folder using <var>[[#JANUS FTP ALLOW|JANUS FTP ALLOW]]</var>.
may be given access rights to a folder using <var>[[Janus FTP Server command reference#JANUS FTP ALLOW|JANUS FTP ALLOW]]</var>.
</ul>
</ul>
In addition, either of these types of access to the folder
In addition, either of these types of access to the folder
Line 207: Line 213:
</ul>
</ul>
If multiple sources are granting access, the user is granted the
If multiple sources are granting access, the user is granted the
highest access specified by any of the sources giving the user access. (The access rights are aggregated.)  
highest access specified by any of the sources giving the user access. (The access rights are aggregated.)


====Home folders====
===Home folders===
Much like UNIX and other folder-tree based systems, FTP has the concept
Much like UNIX and other folder-tree based systems, FTP has the concept
of a '''home folder''' location, where the user is placed after
of a '''home folder''' location, where the user is placed after
successfully connecting to and logging in to the FTP server.
successfully connecting to and logging in to the FTP server.
<var class="product">Janus FTP Server</var> implements
<var class="product">Janus FTP Server</var> implements
this concept with a <var>JANUS</var> command (<var>[[#JANUS FTP HOME|JANUS FTP HOME]]</var>) that permits setting up
this concept with a <var>JANUS</var> command (<var>[[Janus FTP Server command reference#JANUS FTP HOME|JANUS FTP HOME]]</var>) that permits setting up
a home folder for a user, a group of users, all users (excluding anonymous), or the anonymous user.
a home folder for a user, a group of users, all users (excluding anonymous), or the anonymous user.
   
   
Line 222: Line 228:
This is checked at login; a login is rejected if the user
This is checked at login; a login is rejected if the user
does not have at least READ access to their home folder.
does not have at least READ access to their home folder.
 
====The root folder ( / )====
===The root folder ( / )===
In UNIX systems, the root folder is indicated by a forward slash (<tt>/</tt>).
In UNIX systems, the root folder is indicated by a forward slash (<tt>/</tt>).
In <var class="product">Janus FTP Server</var>,
In <var class="product">Janus FTP Server</var>,
Line 242: Line 248:
An anonymous user's password is '''not''' verified.
An anonymous user's password is '''not''' verified.
   
   
===Command overview===
==Command overview==
A detailed reference of the Janus commands that pertain to FTP servers
A detailed reference of the Janus commands that pertain to FTP servers
is presented in [[#Janus FTP Server command reference|"Janus FTP Server command reference"]].
is presented in [[Janus FTP Server command reference|"Janus FTP Server command reference"]].
The following overview is intended to introduce the commands and make it easier
The following overview is intended to introduce the commands and make it easier
to understand the examples in the [[#FTP Server examples|"FTP Server examples"]] section.
to understand the examples in [[Janus FTP Server examples|"Janus FTP Server examples"]].
<dl>
<dl>
<dt>JANUS DEFINE <i>name num</i> FTPSERVER ...
<dt>JANUS DEFINE <i>name num</i> FTPSERVER ...
Line 274: Line 280:
if executed for an <var>[[JANUS DEFINE#type|FTPSERVER]]</var> port.
if executed for an <var>[[JANUS DEFINE#type|FTPSERVER]]</var> port.
</dl>
</dl>
 
===Socket and procedure handling===
==Socket and procedure handling==
This section provides notes about how <var class="product">Janus FTP Server</var> works with sockets
This section provides notes about how <var class="product">Janus FTP Server</var> works with sockets
and <var class="product">Model 204</var> procedures.
and <var class="product">Model 204</var> procedures.
   
   
====Sockets====
===Sockets===
<ul>
<ul>
<li>The <var class="product">Janus FTP Server</var> is implemented as a special type of Janus server socket.
<li>The <var class="product">Janus FTP Server</var> is implemented as a special type of Janus server socket.
Line 287: Line 293:
socket back to a server socket that the FTP client opens.
socket back to a server socket that the FTP client opens.
If you want to enable active file transfers, you must set up a Janus <var>[[JANUS DEFINE#type|CLSOCK]]</var> socket that the FTP server can use.
If you want to enable active file transfers, you must set up a Janus <var>[[JANUS DEFINE#type|CLSOCK]]</var> socket that the FTP server can use.
See <var>[[#JANUS DEFINE|JANUS DEFINE]]</var>, below, for more information.
See <var>[[Janus FTP Server command reference#JANUS DEFINE for FTP|JANUS DEFINE]]</var> for more information.
This lets you have additional security controls: you may place whatever restrictions you
This lets you have additional security controls: you may place whatever restrictions you
like on the client socket based on your site's security policies.
like on the client socket based on your site's security policies.
Line 302: Line 308:
</ul>
</ul>
   
   
The example in [[#FTP client and server interaction|"FTP client and server interaction"]] contains a small demonstration of
The example in [[Janus FTP Server examples#FTP client and server interaction|"FTP client and server interaction"]] contains a small demonstration of
passive FTP socket handling.
passive FTP socket handling.
 
====Procedures====
===Procedures===
<ul>
<ul>
<li>When a procedure is renamed via FTP, the standard <var class="product">Model 204</var> rename operation is performed.
<li>When a procedure is renamed via FTP, the standard <var class="product">Model 204</var> rename operation is performed.
Line 343: Line 349:
</ul>
</ul>
   
   
===Security and Janus FTP Server===
==Security and Janus FTP Server==
A very security-centric approach was taken in the design of the <var class="product">Janus FTP Server</var>.
A very security-centric approach is taken in the design of the <var class="product">Janus FTP Server</var>.
This is seen in the following characteristics:
This is seen in the following characteristics:
<ul>
<ul>
Line 361: Line 367:
command for the FTP server.
command for the FTP server.
Without <var>CLIENTSOCKET</var>, only passive data transfers are enabled.
Without <var>CLIENTSOCKET</var>, only passive data transfers are enabled.
<li>SSL (Secure Sockets Layer) data transmission is supported (as of <var class="product">Sirius Mods</var> version 8.0).
Set by the <var>[[Janus FTP Server command reference#JANUS DEFINE for FTP|JANUS DEFINE SSL]]</var> parameter (or both the <var>SSL</var> and <var>SSLOPT</var> parameters), only explicit invocation of SSL/TLS is supported for <var>FTPSERVER</var> ports, as described at [http://en.wikipedia.org/wiki/FTPS#Methods_of_invoking_security the Wikipedia FTPS entry].
</ul>
</ul>
 
===FTP features not currently supported===
==FTP features not currently supported==
The following FTP features are not currently supported by Janus FTP.
The following FTP features are not currently supported by Janus FTP.
They will be considered for possible future releases.
They will be considered for possible future releases.
Line 370: Line 378:
<li>Client side directory/folder manipulation with <code>mkdir</code>
<li>Client side directory/folder manipulation with <code>mkdir</code>
and <code>rmdir</code> (<code>MKD</code> and <code>RMD</code>)
and <code>rmdir</code> (<code>MKD</code> and <code>RMD</code>)
<li>SSL (Secure Sockets Layer) data transmission
</ul>
</ul>
 
===Supported FTP protocol commands===
==Supported FTP protocol commands==
FTP is essentially a command response protocol, where a server responds to text commands.
FTP is essentially a command response protocol, where a server responds to text commands.
The FTP protocol specifies a set of commands to which a server must respond.
The FTP protocol specifies a set of commands to which a server must respond.
Line 397: Line 404:
<li>DELE, to delete files.
<li>DELE, to delete files.
<li>LIST/NLST, to get folder/directory listings.
<li>LIST/NLST, to get folder/directory listings.
<li>AUTH, to invoke SSL/TLS encrypted transmissions (as of <var class="product">Sirius Mods</var> version 8.0).
</ul>
</ul>
   
   
Line 405: Line 413:
An FTP client constructs these commands
An FTP client constructs these commands
"under the covers" to communicate with the FTP server.
"under the covers" to communicate with the FTP server.
==FTP Server examples==
The following two short examples
show how to set up <var class="product">Janus FTP Server</var>s in an online.
The Janus FTP commands in the examples are introduced in [[#Command overview|"Command overview"]]
and described in greater detail in [[#Janus FTP Server command reference|"Janus FTP Server command reference"]].
===A simple development environment===
In this example, a <var class="product">Janus FTP Server</var> is set up for a
development environment with the following characteristics.
<ul>
<li>Test as well as production procedure files, each type defined
within its own folder (<code>/TEST</code> and <code>/PROD</code>).
These are set up with <var>JANUS FTP ASSIGN</var>.
<li>Everyone can read from the test procedure file.
This is set up with the <var>DEFAULTPRIVS</var> parameter on the <var>ASSIGN</var> for <code>/TEST</code>.
<li>A Janus user group is used for the development team.
This allows fewer FTP commands to be used, since the <var>ALLOW</var> commands can
then reference the group using the <var>USRGROUP</var> parameter.
<li>All developers can update the test procedure file.
This is set up with the <var>JANUS FTP ALLOW</var> for <code>/TEST</code>.
<li>All developers can read the production procedure file.
This is set up with the first <var>JANUS FTP ALLOW</var> for <code>/PROD</code>.
<li>Only the team leader (Moe) can update production.
This is set up with the second <var>JANUS FTP ALLOW</var> for <code>/PROD</code>.
<li>Everyone has the test area as a home folder.
This is set up with the <var>HOME</var> that references <var>ALL</var>.
<li>There will be no anonymous FTP access (no <var>ANONYMOUS</var>
parameter is specified on the <var>JANUS DEFINE</var> for the FTP Server).
<li>Active FTP is supported (perhaps the whole system is behind a firewall,
so there is no exposure, and active permits a greater variety of FTP clients).
Active is enabled by:
<ol>
<li>Specifying a <var>CLIENTSOCKET</var> value on the <var>JANUS
DEFINE</var> for the <code>FTPDEVEL</code> FTP server
<li>Defining a <var>CLSOCK</var> port whose name is the <var>CLIENTSOCKET</var> value
</ol>
</ul>
The commands for the development FTP Server follow.
Notice that to enable active transfers,
the client (<var>CLSOCK</var>) port must be started as well as the main FTP port.
<p class="code">&#42; Create the development team
JANUS DEFUSG STOOGES MOE LARRY CURLEY SHEMP GLW
&#42; FTP server on port 3000
JANUS DEFINE FTPDEVEL 3000 -
  FTPSERVER 4 -
  CLIENTSOCKET FTPDCLIENT -
  AUDTERM -
  PASVPORT 3001 -
  BINDADDR 198.242.244.100
&#42; Client port definition for active transfers
JANUS DEFINE FTPDCLIENT * -
  CLSOCK 5 REMOTE * * -
  SOCKPMAX 5
JANUS CLSOCK FTPDCLIENT ALLOW
&#42; Set up ftp access to test area.
&#42; By default, all users can read it.
JANUS FTP FTPDEVEL ASSIGN /TEST TO FILE FTPTEST DEFAULTPRIVS READ
&#42; Set up ftp access to prod area.
&#42; There is no default access.
JANUS FTP FTPDEVEL ASSIGN /PROD TO FILE FTPPROD
&#42; All developers can update test.
JANUS FTP FTPDEVEL ALLOW /TEST -
  WRITE TO USGROUP STOOGES
&#42; All developers can read prod.
JANUS FTP FTPDEVEL ALLOW /PROD -
  READ TO USGROUP STOOGES
&#42; Moe is the boss; he can update production.
JANUS FTP FTPDEVEL ALLOW /PROD -
  WRITE TO USER MOE
&#42; All start out with test as a home folder.
JANUS FTP FTPDEVEL HOME /TEST TO ALL
&#42; Start them up.
JANUS START FTPDEVEL
JANUS START FTPDCLIENT
</p>
===A simple anonymous FTP Server===
This example sets up a public anonymous FTP Server
from which files may be downloaded &mdash;
a great way to distribute files.
It has the following characteristics:
<ul>
<li>A single folder, <code>/PUB</code>, that anonymous users read from to download files.
<li>The big boss, <code>Moe</code>, is the only one who can upload files to the server.
<li>Prefixing, using the default slash character (<tt>/</tt>), is displayed (see
the <var>PREFIX</var> parameter on the <var>FTP ASSIGN</var> command for <code>/PUB</code>).
<li>Only passive FTP file transfers are permitted (no <var>CLIENTSOCKET</var> is
specified on the <var>JANUS DEFINE</var> command).
</ul>
The commands for an anonymous FTP Server follow:
<p class="code">&#42; Create FTP server on port 2121, anonymous allowed,
&#42; only passive access is provided.
JANUS DEFINE FTPANON 2121 FTPSERVER 10 -
  ANONYMOUS &#42; -
  AUDTERM -
  PASVPORT 2555 -
  BINDADDR 198.242.244.100
&#42; Create public folder and use prefixing.
JANUS FTP FTPANON ASSIGN /PUB TO FILE FTPTEST PREFIX
&#42; Grant Anonymous read access to the /PUB folder.
JANUS FTP FTPANON ALLOW /PUB READ TO ANONYMOUS
&#42; Make user MOE the only person who can place files
&#42; in the Anonymous FTP area.
JANUS FTP FTPANON ALLOW /PUB WRITE TO USER MOE
&#42; Make /PUB the home folder for Anonymous users and Moe.
JANUS FTP FTPANON HOME /PUB TO ANONYMOUS
JANUS FTP FTPANON HOME /PUB TO USER MOE
JANUS START FTPANON
JANUS DISPLAYSOCK FTPANON
</p>
After connecting to the FTP server from his
FTP client, <code>MOE</code> puts/uploads the <code>README</code> file into his home folder, <code>/PUB</code>.
A fragment from a <var>DISPLAY PROC LIST</var> result for the <code>FTPTEST</code> file
confirms the prefixing used in the example.
Procedure <code>README</code> is stored with the folder name as a prefix:
<p class="code">/PUB/README      10/07/04 12:08:28    124 MOE
</p>
===FTP client and server interaction===
To connect to the Janus FTP server,
FTP clients must specify (in the way that is appropriate for the particular tool)
both the host ID and port of the FTP server.
A command line client trying to connect to the <var class="product">Janus FTP Server</var> defined in
[[#A simple anonymous FTP Server|"A simple anonymous FTP Server"]], for example,
might use:
<p class="code">open 198.242.244.100 2121
</p>
The FTP server correctly handles the type of upload (text or binary) that the client FTP package indicates.
This indication may be from an explicit user selection of a type,
or it may be from an FTP client that auto detects the appropriate mode.
By default, the server assumes type <code>A</code>
(ASCII, with translation to EBCDIC) until notified otherwise.
Users can upload multiple files at a time
(in the way that is appropriate for the particular client tool),
although the protocol dictates that multiple-file requests be
handled internally as multiple individual-file transfers.
Users can also upload directories and subdirectories (if and only if
a matching folder structure is predefined for the server).
For more information about defining these folder structures,
see <var>[[#JANUS FTP ASSIGN|JANUS FTP ASSIGN]]</var>.
Since the <var class="product">Janus FTP Server</var> uses a Janus socket port and supports the
<var>[[TRACE (JANUS DEFINE parameter)|TRACE]]</var> parameter (<var>JANUS DEFINE</var> command) and <var>[[JANUS TRACE]]</var> command for the port, you can debug your FTP application by setting <var>TRACE</var> and viewing the <var class="product">Model 204</var> audit trail,
as well as by invoking debugging and viewing your client tool log.
In the audit trail, Janus FTP server and client interactions are helpfully
marked with arrow indicators that identify whether
<code>RK</code> lines are messages from the client to the server
or from the server to the client.
For example, the lines below show Janus <var class="product">SirScan</var> output
(when <var>TRACE</var> is set at its default value, X'00')
for a failed upload of a file to an FTP server.
<code>FTP C->S:</code> identifies messages from the FTP client to the server, and
<code>FTP S->C:</code> the reverse.
<p class="code">19095422 2  1 RK TERM: FTP C->S: PWD
19095422 2  1 RK TERM: FTP S->C: 257 "/TEST/PUBS"
19095422 2  1 RK TERM: FTP C->S: TYPE A
19095422 2  1 RK TERM: FTP S->C: 200 ASCII mode enabled. EBCDIC
                        conversion automatic.
19095423 2  1 RK TERM: FTP C->S: PASV
19095423 2  1 RK TERM: FTP S->C: 227 Entering passive mode
                        (198,242,244,100,12,42)
19095423 3  2 AD MSIR.0114: Processing connection for port FTPPSV3004
                        from 198.242.244.36
19095423 3  2 RK TERM: FTP:      PASV Server Socket connect.
19095423 2  1 RK TERM: FTP C->S: STOR COLORNOTES
19095423 2  1 RK TERM: FTP S->C: 150 storing: "/TEST/PUBS/COLORNOTES"
19095423 3  2 RK TERM: FTP:      PASV Server Socket wakes up.
19095423 3  2 RK TERM: FTP:      PASV Server Open.
19095424 3  2 RK TERM: ***  M204.0620: FILE FTPTEST OPENED
19095424 3  2 RK TERM: ***  M204.1203: FILE FTPTEST WAS LAST UPDATED ON
                        05.038  FEB 07  18.52.41
19095424 3  2 RK TERM: FTP:      PASV Server Start XFER.
19095424 3  2 RK TERM: FTP:      PASV Server End XFER.
19095424 3  2 LI
19095424 3  2 MS M204.1029: USER CONNECTION LOST (PHONE WAS HUNG UP)
19095424 3  2 AD M204.1022: USER RESTARTING SOFTLY
19095424 3  2 ST USERID='MOE' ACCOUNT='NO ACCOUNT' CNCT=12 SQWR=2 CPU=10
                        MOVE=7 AUDIT=13 DKPR=3
19095424 3  2 AD M204.0352: IODEV=15, OK MOE        NO ACCOUNT LOGOUT
                        05.039  FEB 08  19.09.54 -52 C6F2F410
19095424 3  2 AD M204.1024: USER RESTARTED SOFTLY
19095425 3  1 RK TERM: FTP S->C: 500 Line too long, transfer aborted.
</p>
The FTP server in the example is defined much like the one in
[[#A simple development environment|"A simple development environment"]], able to
accommodate active and passive FTP mode.
The audit trail above shows the use of passive FTP, as requested by the FTP client.
The <var class="product">FTP Server</var> dynamically creates a server socket (to which
the FTP client connects for the transfer of the file), which runs on a
separate thread in the online.
When the transfer is done (successfully or not), the dynamically created
socket thread terminates, and the audit trail records a soft restart.
In comparison, the following example shows
the same attempted upload as the one above, but from a command-line client
that uses active FTP only.
The lines beginning with <code>ftp></code> are the user entries in the client tool.
The lines beginning with integers are the FTP server messages
received by the client.
The lines beginning with <code>---></code> are the commands the client actually
sends to the FTP server, as reported by the client's debugging facility.
<p class="code">ftp> put colornotes
---> PORT 198,242,244,36,8,235
200 Port command OK: "198,242,244,36,8,235"
---> STOR colorNotes
150 Storing: "TEST/PUBS/COLORNOTES"
500 Line too long, transfer aborted.
</p>
The client's <var>PORT</var> command above signals an active FTP transfer.
It identifies the
data port (server socket) to which the FTP server's <var>CLSOCK</var> socket must
connect for the upload.
The first four decimal digits following <var>PORT</var> form
the IP address of the FTP client host, and the last two digits form the
TCP address of the port.
In addition to the <var class="product">Model 204</var> <var>DISPLAY PROC LIST</var> command
(or the Sirius <var class="product">SirPro</var> product),
other useful <var class="product">FTP Server</var> debugging and reporting commands are:
<table class="syntaxTable">
<tr><th><var>[[JANUS DISPLAY]]</var>
</th><td>For a display of the FTP Server port definitions
</td></tr>
<tr><th><var>[[JANUS STAT or STATUS|JANUS STATUS]]</var>
</th><td>For a display of the FTP Server port activity (or inactivity)
</td></tr>
<tr><th><var>[[JANUS DISPLAYSOCK]]</var>
</th><td>For a display of the FTP-specific settings like folder mappings and user permissions
</td></tr></table>
==Janus FTP Server command reference==
This section provides a reference for the Janus commands used
to create and manipulate FTP servers.
To create a <var class="product">Janus FTP Server</var>, you must specify:
<ol>
<li>A <var>JANUS DEFINE</var> command to define <var class="product">Model 204</var> as a server on the
TCP/IP network, set a port number to which FTP clients connect, and indicate which remote hosts can
establish connections with the port.
The <var>JANUS DEFINE</var> also can set FTP-specific options to specify additional
listening-port numbers (for the additional server sockets used to handle file
transfers), allow unverified users (Anonymous FTP), and name a client socket port (if needed).
<li>One of each of the following <var>JANUS FTP</var> commands to define FTP server rules:
<ul>
<li><var>FTP ASSIGN</var> to identify the <var class="product">Model 204</var> procedure files
you will expose and the folder names by which those files are identified by FTP clients
<li><var>FTP ALLOW</var> to specify users and grant access privileges to the FTP folders
(may be bypassed for simple systems by specifying a default on <var>FTP ASSIGN</var>)
<li><var>FTP HOME</var> to associate client users with a default folder
</ul>
</ol>
The following commands are described in this section:
<ul>
<li>[[#JANUS DEFINE|JANUS DEFINE]]
<li>[[#JANUS DISPLAYSOCK|JANUS DISPLAYSOCK]]
<li>[[#JANUS FTP|JANUS FTP]]
<li>[[#JANUS FTP ALLOW|JANUS FTP ALLOW]]
<li>[[#JANUS FTP ASSIGN|JANUS FTP ASSIGN]]
<li>[[#JANUS FTP DEASSIGN|JANUS FTP DEASSIGN]]
<li>[[#JANUS FTP DISALLOW|JANUS FTP DISALLOW]]
<li>[[#JANUS FTP HOME|JANUS FTP HOME]]
<li>[[#JANUS FTP ON|JANUS FTP ON]]
<li>[[#JANUS FTP SUFFIX|JANUS FTP SUFFIX]]
</ul>
===JANUS DEFINE===
To define an FTP Server to the online, you use <var>[[JANUS DEFINE]]</var>
with the <var class="term">type</var> option <var>FTPSERVER</var>.
This command must be issued before any other <var>JANUS FTP</var> commands.
As with other Janus servers, the server will not be available for use until
a <var>[[JANUS START]]</var> has been issued for it.
====Syntax for JANUS DEFINE with FTPSERVER====
<p class="syntax">JANUS DEFINE portname portnum FTPSERVER maxcon -
    [ ANONYMOUS maxanon | * ]    -
    [ ANONUSER anonuserid ]      -
    [ CLIENTSOCKET socketname ]  -
    [ PASVPORT startportnum ]    -
    [ other_parms ]
</p>
====Syntax terms====
<table class="syntaxTable">
<tr><th>portname</th>
<td>The name of the FTP port being created.
This name can then be referenced by Janus FTP commands, as well as other Janus commands. </td></tr>
<tr><th>portnum</th>
<td>The port number to listen on for FTP connections. In FTP terminology, this is what is referred to as the '''control port'''. </td></tr>
<tr><th>maxcon</th>
<td>The maximum number of simultaneous FTP sessions supported by this server. </td></tr>
<tr><th nowrap><var>ANONYMOUS [</var><var class="term">maxanon</var> <var>| *]</var> </th>
<td>Indicates that anonymous access is permitted. It must be followed by a number (<var class="term">maxanon</var>) or an asterisk (<tt>*</tt>):
<ul>
<li><var class="term">maxanon</var> is an integer in the range
from 1 to <var class="term">maxcon</var> that indicates how many of the
<var class="term">maxcon</var> sessions may be used for anonymous sessions.
This allows the system manager to control the amount of resources that anonymous
users can consume.
Many FTP sites limit anonymous connections.
<li>An asterisk indicates that all <var class="term">maxcon</var> sessions are available for
anonymous FTP use.
</ul>
If the <var>ANONYMOUS</var> parameter is not specified, no anonymous access is permitted.
<p>
If anonymous access is permitted, the default name of the anonymous
user is <code>ANONYMOUS</code>.
This name can be overridden with the <var>ANONUSER</var> parameter. </p>
<p>
The <var class="product">FTP Server</var> does not attempt to verify an anonymous user password,
but you must specify <var>FTP HOME</var> and <var>FTP ALLOW</var> rules for <var>ANONYMOUS</var>. </p></td></tr>
<tr><th><var>ANONUSER</var> user </th>
<td>Lets you change the name of the anonymous user. It may be specified only if <var>ANONYMOUS</var> is also specified.
<var class="term">user</var> must be ten characters or less. </td></tr>
<tr><th nowrap><var>CLIENTSOCKET</var> socketname  </th>
<td>Names the client socket port to use to open connections back to the FTP client, if the client requests active file transfers.
On active transfers, the FTP server is required by the protocol to open a client connection back to a server port opened by the FTP client.
<p>
If this parameter is '''not''' specified, active file transfers are '''not'''
permitted on this FTP server port. </p>
<p>
The name is not validated when the <var>DEFINE</var> command is issued, but when
an active transfer is attempted.  </p></td></tr>
<tr><th><var>PASVPORT</var> <i>startportnum</i> </th>
<td>The first port number to use for passive sockets. For passive file transfers, an FTP server opens an additional server socket, to which the client is requested to connect for data transfers. Each such socket needs a port to listen on. For any given FTP server, a block of <var class="term">maxcon</var> port numbers starting at <var class="term">startportnum</var> is used for passive file transfers.
<p>
If <var>PASVPORT</var> is not specified, its default is 5000. If it is specified, the value must be at least 1000 and no greater than 32K. </p></td></tr>
<tr><th><i>other-parms</i>  </th>
<td>One or more of the other options that are valid for a <var>JANUS DEFINE</var> that creates a Janus server socket port, with the exception of <var>OPEN</var>, <var>CMD</var>, <var>NEWSESOPEN</var>, and <var>NEWSESCMD</var>.
<p>
'''Note:'''
If you specify <var>XTAB</var> (a translate table, described in <var>[[XTAB (JANUS DEFINE parameter)|XTAB]]</var>) the table you indicate is used on all file transfers initiated on this server, including active transfers done with a client socket port.  </p></td></tr>
</table>
====Examples====
<ul>
<li>The following <var>JANUS DEFINE</var> commands specify <var calss="product">FTP Servers</var>.
The first defines a server with control port 1666 that is supportive of
active and passive transfers.
The second defines a server that supports only passive transfers.
<p class="code">JANUS DEFINE FTP01 1666 FTPSERVER 8  -
  AUDTERM -
  XTAB FTP.X  -
  ANONYMOUS 1 ANONUSER MOE -
  CLIENTSOCKET FTPDTP -
  BINDADDR 198.242.244.47 -
  TRACE 8
JANUS DEFINE FTP02 1667 FTPSERVER 2  -
  AUDTERM PASVPORT 2000
</p>
<li>The following <var>JANUS DEFINE</var> specifies the client socket for active transfers
for the first FTP server defined above:
<p class="code">JANUS DEFINE FTPDTP * CLSOCK 5 REMOTE * * -
  SOCKPMAX 5 -
  TRACE 8
JANUS CLSOCK FTPDTP ALLOW
</p>
</ul>
===JANUS DISPLAYSOCK===
If <var>JANUS DISPLAYSOCK</var> (see also <var>[[JANUS DISPLAYSOCK]]</var> is issued for an FTP port, in
addition to its usual output, it displays the FTP entities defined for the port.
These include folders created with <var>FTP ASSIGN</var> and rules set up with
<var>FTP ALLOW</var>, <var>FTP HOME</var>, <var>FTP ON</var>, and <var>FTP SUFFIX</var>.
For example, here is sample output from issuing
<var>JANUS DISPLAYSOCK</var> output for the FTP Server defined in [[#A simple anonymous FTP Server|"A simple anonymous FTP Server"]]:
<p class="code">JANUS DISPLAYSOCK FTPANON
Folders:
/PUB maps to file: FTPTEST prefixed, separator=/
Permissions:
The Anonymous user can READ /PUB
User MOE can WRITE /PUB
Home folders:
The Anonymous user has home: /PUB
User MOE has home: /PUB
Suffixes:
... None
Overrides:
... None
</p>
===JANUS FTP===
The <var>JANUS FTP</var> command defines the rules for a <var class="product">Janus FTP Server</var>
running on a <var class="product">Janus Sockets</var> FTP (<var>FTPSERVER</var>) port.
These rules primarily control access to the files
exposed by the FTP server.
====JANUS FTP command syntax====
<p class="syntax">JANUS FTP portname rule_type other_parameters
</p>
The first two parameters are positional and are required:
<table class="syntaxTable">
<tr><th>portname</th>
<td>The name (thirty characters or fewer) of the FTP port, or a pattern specifying a set of ports, for which the rule is being defined. Wildcards are allowed. The Janus definition of the port or ports must include the <var>FTPSERVER</var> parameter. </td></tr>
<tr><th>rule_type</th>
<td>The rule_type specifies the sort of rule being specified for the port(s).
Valid rule_types are:
<table class="syntaxTable">
<tr><th><var>ASSIGN</var> </th>
<td>Creates FTP folders and maps them to <var class="product">Model 204</var> <var class="product">Janus Sockets</var> files, as described in [[#Folder mapping|"Folder mapping"]]. </td></tr>
<tr><th><var>DEASSIGN</var></th>
<td>Removes FTP folders. </td></tr>
<tr><th><var>ALLOW</var></th>
<td>Grants read or write access to a folder created with <var>FTP ASSIGN</var>. </td></tr>
<tr><th><var>DISALLOW</var></th>
<td>Revokes read or write access to a folder. </td></tr>
<tr><th><var>HOME</var></th>
<td>Specifies a home folder (initial location at login) for a user. </td></tr>
<tr><th><var>ON</var></th>
<td>Sets up overrides, by specifying files to be opened and commands to be executed when a specific FTP operation is performed. </td></tr>
<tr><th><var>SUFFIX</var></th>
<td>Allows specification of the transfer mode (text or binary) of procedures/files by suffix (for example, <code>.html</code>, <code>.xml</code>). </td></tr>
</table>  </td></tr>
<tr><th nowrap>other_ parameters</th>
<td>The additional parameters allowed for the <var>JANUS FTP</var> command depend on the <var class="term">rule_type</var> that is specified. The various rule types and their parameters are described in the following alphabetically ordered sections.  </td></tr>
</table>
You must specify at least three <var>JANUS FTP</var> commands &mdash; one each of <var>FTP
ASSIGN</var>, <var>FTP ALLOW</var>, and <var>FTP HOME</var> &mdash; and
it typically takes a set of <var>JANUS FTP</var> commands to fully specify
the rules for an FTP server port.
For instance, it
may take a number of commands to specify the
folders that are available for access, the users
that may connect, and the privileges and home folders of the users.
In practice, the first of the <var>JANUS FTP</var> commands to issue is <var>FTP ASSIGN</var>.
===JANUS FTP ALLOW===
This command is used to grant user access to a folder in addition to any
access granted via a <var>DEFAULTPRIVS</var> parameter on the
<var>[[#JANUS FTP ASSIGN|FTP ASSIGN]]</var> for the server port.
====JANUS FTP ALLOW comand syntax====
<p class="syntax">JANUS FTP portname ALLOW foldername READ | WRITE  -
  TO [USER user] | [USGROUP usgroup] | ANONYMOUS | ALL
</p>
====Syntax terms====
<table class="syntaxTable">
<tr><th>portname</th>
<td>Must be a previously defined <var class="product">Janus FTP Server</var> port.  </td></tr>
<tr><th>foldername</th>
<td>A folder previously created with JANUS FTP ASSIGN.  </td></tr>
<tr><th><var>READ</var> or <var>WRITE</var> </th>
<td>The folder access privileges being granted.
One of these must be specified:
<table>
<tr><th><var>READ</var></th>
<td>FTP <code>get</code> (<code>RETR</code> command) and directory listings (<code>LIST</code>) are permitted. Also, the FTP client or user can <code>cd</code> (change directory, <code>CWD</code>) into this directory. </td></tr>
<tr><th><var>WRITE</var></th>
<td>READ privileges plus permission for FTP <code>put</code>, <code>delete</code>, and <code>rename</code> (<code>STOR</code>, <code>DEL</code>, <code>RNFR</code>, and <code>RNTO</code>). </td></tr>
</table>  </td></tr>
<tr><th><var>TO</var> </th>
<td>To whom access is being granted to <var class="term">foldername</var>.
One of these options must be specified, and only one of these per
folder may be issued.
To modify an earlier <var>ALLOW</var> rule, first use <var>[[#JANUS FTP DISALLOW|FTP DISALLOW]]</var>.
<table class="syntaxTable">
<tr><th><var>USER</var> user</th>
<td>A <var class="product">Model 204</var> user ID. The user is not checked for existence when this command is issued. </td></tr>
<tr><th nowrap><var>USRGROUP</var> usrgroup</th>
<td>A user group created with the <var>[[JANUS DEFINEUSGROUP]]</var> command. The group is not checked for existence when this command is issued. </td></tr>
<tr><th><var>ANONYMOUS</var> </th>
<td>Anonymous users (see [[#Anonymous FTP|"Anonymous FTP"]]).
<tr><th><var>ALL</var> </th>
<td>All <var class="product">Model 204</var> users (except the <var>ANONYMOUS</var> user). </td></tr>
</table>  </td></tr>
</table>
Examples of valid <var>FTP ALLOW</var> commands follow:
<p class="code">JANUS FTP FTP01 ALLOW /ANON READ TO ANONYMOUS
JANUS FTP FTP01 ALLOW /GLWHOME WRITE TO USER GLW
JANUS FTP FTP01 ALLOW /ALL READ TO ALL
JANUS FTP FTP01 ALLOW /GLWHOME READ TO USGROUP FTP
</p>
For more information about folder access, see [[#Folder security|"Folder security"]].
===JANUS FTP ASSIGN===
This command creates an FTP folder for a previously defined FTP port.
For more information about folder creation, see [[#Folder mapping|"Folder mapping"]].
====JANUS FTP ASSIGN comand syntax====
<p class="syntax">JANUS FTP portname ASSIGN foldername -
  [ TO FILE filename ]              -
  [ DEFAULTPRIVS READ | WRITE ]    -
  [ PREFIX [. | /] ]
</p>
====Syntax terms====
<table class="syntaxTable">
<tr><th>portname </th>
<td>Must be a previously defined <var class="product">Janus FTP Server</var> port. </td></tr>
<tr><th>foldername </th>
<td>The name of the FTP folder being created. For more information about naming rules, see [[#Folder names|"Folder names"]]. </td></tr>
<tr><th nowrap><var>TO FILE</var> filename </th>
<td>The <var class="product">Model 204</var> procedure file being associated with <var class="term">foldername</var>. </td></tr>
<tr><th><var>DEFAULTPRIVS</var> </th>
<td>The privileges a user gets unless a <var>JANUS FTP ALLOW</var> rule gives them greater access. If <var>DEFAULTPRIVS</var> is not specified, no access is permitted except that granted by <var>FTP ALLOW</var> rules.
Default privileges do <b>not</b> apply to <var>ANONYMOUS</var> access. Any <var>ANONYMOUS</var> access must be granted with an <var>FTP ALLOW</var> rule. The privileges allowed are <var>READ</var> and <var>WRITE</var>, one of which must be specified, as discussed in [[#JANUS FTP ALLOW|JANUS FTP ALLOW]]. </td></tr>
<tr><th><var>PREFIX</var> </th>
<td>Invokes prefixing for this folder, as described in [[#Prefixing|"Prefixing"]]. Files uploaded to this folder by FTP clients are stored with the name of the folder prefixed to the filename. File <code>MYFILE</code> uploaded to folder <code>ANNUAL</code> becomes procedure <code>/ANNUAL/MYFILE</code>.
<var>PREFIX</var> may be be followed by a "prefix character" &mdash; forward slash ( / ) or period (.) &mdash; which is used as the separator in folder names. The default is a forward slash.
'''Note:''' The characters in the prefix string '''are''' added to and <b>do</b> increase the length of the procedure name, whose <var class="product">Model 204</var> limit is 255. </td></tr>
</table>
You can dynamically assign folders once a port is started, but you may not
issue multiple <var>ASSIGN</var> commands for the same folder.
To reassign a folder, you must first remove the assignment using
<var>[[#JANUS FTP DEASSIGN|JANUS FTP DEASSIGN]]</var>).
You may not deassign a folder once a port is started, however; in this case,
you must first drain the folder using the <var>[[JANUS DRAIN]]</var> command.
If you use a single <var>JANUS FTP ASSIGN</var> to create a folder such
as <code>/A/B/C</code>, the following FTP change directory command works as expected:
<p class="code">cd /A/B/C
</p>
However, you cannot use <code>cd</code> to move to the
intermediate folder levels <code>/A</code> and <code>/A/B</code>, unless each of these levels is also
defined with an individual <var>JANUS FTP ASSIGN</var> command.
In addition to defining <code>/A</code>, <code>/A/B</code>, and <code>/A/B/C</code> as three separate folders with three <var>ASSIGN</var> commands, allowing navigation to all three levels also requires granting at least <var>READ</var> access at each level.
The following statements create this three-level folder structure:
<p class="code">JANUS FTP FTPJ1 ASSIGN /A TO FILE JPROC DEFAULTPRIVS READ
JANUS FTP FTPJ1 ASSIGN /A/B TO FILE JPROC DEFAULTPRIVS READ
JANUS FTP FTPJ1 ASSIGN /A/B/C TO FILE JPROC DEFAULTPRIVS READ
</p>
The statements above create three folders that point to the same underlying procedure file.
FTP clients will display and be able to navigate up and down this directory tree.
In this case, however, clients will see the same procedures at any folder level they view.
You can adjust this outcome by adding prefixing to the assignments:
<p class="code">JANUS FTP FTPJ1 ASSIGN /A TO FILE JPROC      -
  DEFAULTPRIVS READ PREFIX
JANUS FTP FTPJ1 ASSIGN /A/B TO FILE JPROC    -
  DEFAULTPRIVS READ PREFIX
JANUS FTP FTPJ1 ASSIGN /A/B/C TO FILE JPROC  -
  DEFAULTPRIVS READ PREFIX
</p>
As a result:
<ul>
<li>The names of all files uploaded to these FTP server folders are prefixed
with the name of the folder to which they are uploaded.
The <code>INFO</code> file uploaded to folder <code>/A/B/C</code> is stored as <code>/A/B/C/INFO</code>.
<li>To clients, a display of the list of the files in any folder contains
only the files that are prefixed with that folder name.
<p>
'''Note:''' Such a display may also include files that belong to a subfolder:
for example, the <code>/A/B/C/INFO</code> file will be displayed
in a list of the files in folder /A as <code>/A/B/C/INFO</code>,
in a list of the files in folder
B/ as <code>/B/C/INFO</code>, and
in a list of the files in folder C/ as <code>/C/INFO</code>. </p>
</ul>
An alternative to prefixing in this case is
to assign each folder to its own procedure file, as shown below.
Then a display to a client of the list of the files in any folder contains
all the files that are stored in that procedure file, without regard
for prefixes, if any, or for how the files got there:
<p class="code">JANUS FTP FTPJ1 ASSIGN /A TO FILE JPROC1 DEFAULTPRIVS READ
JANUS FTP FTPJ1 ASSIGN /A/B TO FILE JPROC2 DEFAULTPRIVS READ
JANUS FTP FTPJ1 ASSIGN /A/B/C TO FILE JPROC3 DEFAULTPRIVS READ
</p>
Of course, in all the examples above, you can use <var>FTP ALLOW</var> commands (along with or in place of the <var>DEFAULTPRIVS</var> parameter of <var>FTP ASSIGN</var>) to diversify user access.
For example:
<p class="code">JANUS FTP FTPJ1 ASSIGN /A TO FILE JPROC1 DEFAULTPRIVS WRITE
JANUS FTP FTPJ1 ASSIGN /A/B TO FILE JPROC2 DEFAULTPRIVS READ
JANUS FTP FTPJ1 ASSIGN /A/B/C TO FILE JPROC3 DEFAULTPRIVS READ
JANUS FTP FTPJ1 ALLOW /A/B WRITE TO USGROUP DEV
JANUS FTP FTPJ1 ALLOW /A/B/C WRITE TO USER SUPER
</p>
A benefit of predefining a folder tree like <code>/A</code>, <code>/A/B</code>, and <code>/A/B/C</code>
is that, by making the folder names match the names of the directories on your workstation,
you can then upload entire directories and subdirectories in one request, if your FTP client permits.
The <var class="product">Janus FTP Server</var> does not currently support client requests to
create (or delete or rename) a folder, so the required
directry/subdirectory structure must preexist on the server
before a client can upload files arranged in such a structure.
===JANUS FTP DEASSIGN===
This command removes an existing FTP folder from a Janus FTP port.
====JANUS FTP ASSIGN comand syntax====
<p class="syntax">JANUS FTP portname DEASSIGN foldername
</p>
====Syntax terms====
<table>
<tr><th><i>portname</i>
</th><td>Must be a previously defined <var class="product">Janus FTP Server</var> port.
</td></tr>
<tr><th><i>foldername</i>
</th><td>A folder previously created with <var>JANUS FTP ASSIGN</var>.
</td></tr></table>
====Usage notes====
Once an <var class="product">FTP Server</var> port is started, no <var>FTP DEASSIGN</var> commands may be issued for it;
the port must first be drained (using <var>[[JANUS DRAIN]]</var>).
A folder may not be removed with <var>DEASSIGN</var> if it is referred to by <var>FTP ALLOW</var>,
<var>FTP HOME</var>, or <var>FTP ON</var> rules.
Example <var>FTP DEASSIGN</var> commands follow:
<p class="code">JANUS FTP FTP04 DEASSIGN /TEMPAREA
JANUS FTP FTPANON DEASSIGN /JUNK
</p>
===JANUS FTP DISALLOW===
This command revokes folder access rights that were previously granted using <var>JANUS FTP ALLOW</var>.
====JANUS FTP DISALLOW comand syntax====
<p class="syntax"> JANUS FTP portname DISALLOW foldername -
    TO [USER user] | [USGROUP usgroup] | ANONYMOUS | ALL
</p>
====Syntax terms====
<table class="syntaxTable">
<tr><th>portname</th>
<td>Must be a previously defined <var class="product">Janus FTP Server</var> port. </td></tr>
<tr><th>foldername</th>
<td>A folder previously created with JANUS FTP ASSIGN. </td></tr>
<tr><th><var>TO</var> </th>
<td>Specifies whose access to <var class="term">foldername</var> is to be taken away.
Users '''not''' previously specified by <var>FTP ALLOW</var> are ignored.
One of these options must be specified:
<table class="syntaxTable">
<tr><th><var>USER</var> user </th>
<td>A <var class="product">Model 204</var> user ID. The user is not checked for existence when this command is issued. </td></tr>
<tr><th><var>USRGROUP</var> usrgroup </th>
<td>A user group created with the <var>[[JANUS DEFINEUSGROUP]]</var> command. The group is not checked for existence when this command is issued. </td></tr>
<tr><th><var>ANONYMOUS</var> </th>
<td>Anonymous (see [[#Anonymous FTP|"Anonymous FTP"]] users. </td></tr>
<tr><th><var>ALL</var> </th>
<td>All <var class="product">Model 204</var> users (except the ANONYMOUS user). </td></tr>
</table> </td></tr>
</table>
An example <var>DISALLOW</var> command follows:
<p class="code">JANUS FTP FTP01 DISALLOW /PUB0 TO USER XXXX
</p>
===JANUS FTP HOME===
This command identifies the folder where an FTP user is placed when
they log in.
Home folders are described further in [[#Home folders|"Home folders"]].
====JANUS FTP HOME comand syntax====
<p class="syntax">JANUS FTP portname HOME foldername    -
  TO [USER user] | [USGROUP usgroup] | ANONYMOUS | ALL
</p>
====Syntax terms====
<table class="syntaxTable">
<tr><th>portname</th>
<td>Must be a previously defined <var class="product">Janus FTP Server</var> port. </td></tr>
<tr><th>foldername</th>
<td>A folder previously created with <var>JANUS FTP ASSIGN</var>.  </td></tr>
<tr><th><var>TO</var>  </th>
<td>The TO clause identifies for whom a home folder is to be set up.
One of these options must be specified:
<table class="syntaxTable">
<tr><th><var>USER</var> user </th>
<td>A <var class="product">Model 204</var> user ID. The user is not checked for existence when this command is issued. </td></tr>
<tr><th><var>USRGROUP</var> usrgroup </th>
<td>A user group created with the <var>[[JANUS DEFINEUSGROUP|JANUS DEFUSG]]</var> command. The group is not checked for existence when this command is issued. </td></tr>
<tr><th><var>ANONYMOUS</var> </th>
<td>Anonymous users (see [[#Anonymous FTP|"Anonymous FTP"]]). </td></tr>
<tr><th><var>ALL</var> </th>
<td>All <var class="product">Model 204</var> users (except the <var>ANONYMOUS</var> user). </td></tr>
</table> </td></tr>
</table>
'''Note:''' All <var class="product">Janus FTP Server</var> users must have a home folder assigned.
When a user logs in, the <var>JANUS FTP HOME</var> commands for the port are used as a rule
set to select a home folder.
The following steps are then applied to the home rule set to determine a home folder:
<ol>
<li>If the user is <var>ANONYMOUS</var> and there is an <var>ANONYMOUS</var> entry, use it;
but if there is no <var>ANONYMOUS</var> entry, reject the login.
<li>If the user is '''not''' <var>ANONYMOUS</var>, do the following:
<ol>
<li>If an <var>FTP HOME</var> rule specifies the user on a <var>USER</var>
clause, use that folder.
<li>If no <var>USER</var> clause matches, but the user is in a group
specified in an <var>FTP HOME</var> rule <var>USGROUP</var>,
use that folder.
<li>If no <var>USGROUP</var> group contains the user, but an <var>ALL</var> rule is present, use that folder.
<li>If no <var>FTP HOME</var> rule matches, the login is rejected.
</ol>
</ol>
Example <var>FTP HOME</var> commands follow:
<p class="code">JANUS FTP FTP01 HOME /GLW2HOME TO USER GLW2
JANUS FTP FTP01 HOME /ALL TO ALL
JANUS FTP FTP01 HOME /GLWHOME TO USGROUP FTP
</p>


===JANUS FTP ON===
==See also==
This command lets you override the default processing of an FTP operation (service command) with
The following topics complete the description of <var class="product">Janus FTP Server</var> support:
your own version.
For additional information about writing <var>JANUS FTP</var> overrides,
see [[#Overriding FTP protocol commands|"Overriding FTP protocol commands"]].
====JANUS FTP ON comand syntax====
<p class="syntax">JANUS FTP portname ON foldername | *        -
  STOR | RETR | LIST | RNTO | DELE          -
  [OPEN fg [[AND fg] ...]] CMD cmd [[AND cmd] ...] | DEFAULT
</p>
====Syntax terms====
<table class="syntaxTable">
<tr><th>portname</th>
<td>Must be a previously defined <var class="product">FTP Server</var> port. </td></tr>
<tr><th>foldername</th>
<td>A folder previously created with <var>JANUS FTP ASSIGN</var>.
If an asterisk (<tt>*</tt>) is specified instead of a folder name, the override is
used for all folders on the port. </td></tr>
<tr><th>,var>STOR | RETR | LIST | RNTO | DELE</var> </th>
<td>Names the operation being overriden (one of the following must be selected).
For a list of all the FTP commands supported by Janus FTP, including those not available for override,
see [[#Supported FTP protocol commands|"Supported FTP protocol commands"]].
<table>
<tr><th>This option </th>
<th>Overrides this operation </th></tr>
<tr><th><var>STOR</var> </th>
<td>FTP <code>put</code> (upload files) </td></tr>
<tr><th><var>RETR</var> </th>
<td>FTP <code>get</code> (download files) </td></tr>
<tr><th><var>LIST</var> </th>
<td>FTP <code>ls</code> or <code>dir</code> (list files in wide or narrow format) </td></tr>
<tr><th><var>RNTO</var> </th>
<td>FTP <code>rename</code> </td></tr>
<tr><th><var>DELE</var> </th>
<td>FTP <code>delete</code> </td></tr>
</table> </td></tr>
<tr><th>fg  </th>
<td>Lists one or more files or groups to open before the commands
specified on the <var>CMD</var> clause (see below) are run.
If you specify multiple files or groups, they must be separated by <var>AND</var> keywords.
Each <var class="term">fg</var> term has the following format, where you
can specify individual open privileges (which default to <code>X'0221'</code>):
<p class="code">[FILE | GROUP] &'italic(fgname) [[WITH] &'italic(privs)]
</p>  </td></tr>
<tr><th><var>CMD</var> cmd  </th>
<td>Lists one or more <var class="product">Model 204</var> commands to execute to
perform the override.
If more than one is specified, they must be separated by <var>AND</var> keywords.
Any command that contains blanks must be enclosed in quotes. The total length of commands
plus one overhead byte per command may not exceed 255 bytes. </td></tr>
<tr><th><var>DEFAULT</var> </th>
<td>Resets any previous <var>FTP ON</var> for the folder,
restoring the default handling of the operation specified in that <var>ON</var> rule.
In short, to reverse an <var>ON</var>, use <var>DEFAULT</var>.
'''Note:''' For a given operation and folder, any previous <var>ON</var> rule must be
be turned off with <var>DEFAULT</var> before a new <var>FTP ON</var> is issued. </td></tr>
</table>
Example <var>FTP ON</var> commands follow:
<p class="code">JANUS FTP FTP05 ON /SPLAT STOR -
  OPEN FTPTEST WITH X'BFFF' CMD 'I POV.STOR'
JANUS FTP FTP05 ON /SPLAT LIST -
  OPEN FILE FTPTEST CMD 'I POV.LIST'
JANUS FTP FTP05 ON * LIST CMD 'SUB1'
</p>
===JANUS FTP SUFFIX===
This command lets you specify any file types that a <var class="product">Janus FTP Server</var> should treat as
text data for storage and translation purposes (even if received under BINARY
transfer mode).
This permits Janus FTP to work with those FTP clients that incorrectly send all
files in BINARY mode, even those that are text data.
====JANUS FTP SUFFIX comand syntax====
<p class="syntax">JANUS FTP portname SUFFIX suffix [TEXT | DEFAULT]
</p>
====Syntax terms====
<table class="syntaxTable">
<tr><th>portname </th>
<td>Must be a previously defined <var class="product">Janus FTP Server</var> port. </td></tr>
<tr><th>suffix </th>
<td>A file-type suffix that ends a procedure name (preceded by a period in the procedure name). Forexample, you use <code>HTML</code> to match procedures whose names are of form <code>WHATEVER.HTML</code>. </td></tr>
<tr><th><var>TEXT</var> </th>
<td>Procedures with names ending in <var class="term">suffix</var> will be handled as text data (not binary), even if the FTP transfer mode is <code>BINARY</code>. </td></tr>
<tr><th><var>DEFAULT</var> </th>
<td>Restores the default behaviour (no special handling); can be used to turn off a previously issued <var>FTP SUFFIX</var> command. </td></tr>
</table>
The FTP protocol is based on the assumption that the FTP client will
toggle between ASCII and BINARY mode as needed based on the type of the file.
It is the client's responsibility to select the proper file transfer mode.
Some (poorly behaved) FTP clients, however, send all files in BINARY mode.
<var class="product">Janus FTP Server</var> uses base64 encoded format to store
files that are uploaded (FTP <code>put</code> or <code>stor</code>)
in BINARY FTP mode (type I).
The <var>FTP SUFFIX</var> command is used to prevent text file types from being
stored in base64.
Janus file storage formats are described further in the <var class="product">Janus
Web Server</var> documentation.
Example <var>FTP SUFFIX</var> commands follow:
<p class="code">JANUS FTP FTP01 SUFFIX HTML TEXT
JANUS FTP FTP01 SUFFIX XML TEXT
JANUS FTP FTP01 SUFFIX FOO DEFAULT
</p>
==Integrating Janus FTP and Janus Web Server==
If you have <var class="product">Janus Web Server</var>, you may have set up rules
to simulate folders using <var>[[JANUS WEB ON]]</var>.
For example, for your web server, you might have this rule:
<p class="code">JANUS WEB W3216 ON /CGIBIN/* -
  OPEN FILE FTPTEST WITH X'BFFF' -
  CMD 'INCLUDE /CGIBIN/*'
</p>
This invokes procedures whose names start with <code>/CGIBIN/</code>, such as <code>/CGIBIN/HELLO.UL</code>.
With Janus FTP, you can set up a prefixed folder to automatically prepend the <code>/CGIBIN/</code> when storing
a procedure.
For example:
<p class="code">&#42; Map to web rule
JANUS FTP FTP01 ASSIGN /CGIBIN TO FILE FTPTEST PREFIX
JANUS FTP FTP01 ALLOW  /CGIBIN WRITE TO USER GLW
</p>
If you then execute the following sequence of FTP commands from an FTP client,
the <code>HELLO.UL</code> procedure is stored as <code>/CGIBIN/HELLO.UL</code>,
which matches the web rule pattern above:
<p class="code">CD /CGIBIN
PUT HELLO.UL
</p>
The procedure can then be accessed from a web browser
as <code>http://your-url-goes-here/cgibin/hello.ul</code>.
==Overriding FTP protocol commands==
For custom processing, you can develop a <var class="product">User Language</var> procedure
to replace the native Janus FTP implementation of an FTP operation
(that is, of an FTP "service command" like <code>STOR</code>,
typically implemented as <code>put</code>).
As described in <var>[[#JANUS FTP ON|JANUS FTP ON]]</var>,
you specify such an override using the <var>JANUS FTP ON</var> command.
The override can apply to a specific folder or to all folders.
You run an override procedure using a <var class="product">Model 204</var> command
that is specified as part of the <var>CMD</var> clause of <var>JANUS FTP ON</var>.
The <var>CMD</var> clause can be an <var>INCLUDE</var>
of a procedure, or it can be an invocation of a subsystem that
implements the operation you are overriding.
You may also specify one or more files or groups to be opened prior to running the <var>CMD</var> command(s).
An override needs to have access to certain values (such as a file name) to be
able to perform the operation.
It also needs to be able to signal whether an operation failed.
These cababilities are provided as a series of $functions, which are described
in the next section.
You may override the following FTP operations:
<table>
<tr><th>FTP command </th>
<th>Operation </th></tr>
<tr><th><var>STOR</var> </th>
<td>FTP <code>put</code> </td></tr>
<tr><th><var>RETR</var> </th>
<td>FTP <code>get</code> </td></tr>
<tr><th><var>RNFR/RNTO</var> </th>
<td>FTP <code>rename</code> </td></tr>
<tr><th><var>DELE</var> </th>
<td>FTP <code>delete</code> </td></tr>
<tr><th><var>LIST</var> </th>
<td>FTP folder list (<code>ls</code>, <code>dir</code>) </td></tr>
</table>
===The Override API $functions===
The override functions, described below, provide the needed information and control to write overrides.
They all take no arguments.
If called on a non-<var class="product">FTP Server</var> thread,
they do nothing, and they return either a zero length string or <code>0</code>,
depending on whether the function returns a number or a string.
This allows you to scan for syntax errors on
an interactive thread before running them on a the server.
<table>
<tr><th>$Ftp_Fail </th>
<td><div id="$Ftp_Fail"></div>Returns a failure status code (500) to the FTP client when the override finishes. Unless this function is called, a success status code is returned when the override finishes. </td></tr>
<tr><th>$Ftp_Get_Command </th>
<td><div id="$Ftp_Get_Command"></div>Returns the FTP command that is the subject of the override. It is useful in a case where one override procedure implements multiple overrides. Its value is always one of the following:
<p class="code">DELE
LIST
NLST
RETR
RNTO
STOR
</p>
[[#Writing overrides|"Writing overrides"]] provides specific comments about overriding each of these commands, and it includes some sample overrides. </td></tr>
<tr><th>$Ftp_Get_Current_File </th>
<td><div id="$Ftp_Get_Current_File"></div>Returns the <var class="product">Model 204</var> file mapped to the current folder, if any. If no such file exists, this function returns a null (zero length) string. </td></tr>
<tr><th>$Ftp_Get_Current_Folder </th>
<td><div id="$Ftp_Get_Current_Folder"></div>Returns the name of the current folder, (for example, <code>/PUB</code>). </td></tr>
<tr><th>$Ftp_Get_Operand </th>
<td><div id="$Ftp_Get_Operand"></div>Returns the value of the entity being operated on by the FTP command that is being overridden. This value varies with the command being overridden. See the individual sections in [[#Writing overrides|"Writing overrides"]] for what this function returns in each context. </td></tr>
<tr><th>$Ftp_Get_Old_Name </th>
<td><div id="$Ftp_Get_Old_Name"></div>Returns the name of the procedure being renamed. <var>$Ftp_Get_Old_Name</var> is used only for overriding rename (RNTO). If called in a context other than rename, it returns a null (zero length) string. </td></tr>
<tr><th>$Ftp_Get_Prefix </th>
<td><div id="$Ftp_Get_Prefix"></div>Returns the prefix character. if the folder is using prefixing; returns a zero length string if the folder is not prefixed. Its value is always one of the following:
<ul>
<li><code>.</code> (period)
<li><code>/</code> (slash)
<li><code>''</code> (null string) </ul> </td></tr>
<tr><th>$Ftp_Get_Transfer_Type </th>
<td><div id="$Ftp_Get_Transfer_Type"></div>Returns the current FTP transfer mode, as specified by the FTP client. Its value is either of these:
<ul>
<ul>
<li><code>I</code> (binary)
<li>[[Janus Sockets User Language coding considerations]]
<li><code>A</code> (ASCII text) </ul> </td></tr>
<li>[[Janus FTP Server examples]]
</table>
<li>[[Janus FTP Server command reference]]
 
<li>[[Integrating Janus FTP and Janus Web Server]]
===Writing overrides===
<li>[[Overriding FTP protocol commands]]
The following sections present the requirements for an override for a particular operation, along with the
override API $functions that are applicable.
====Overriding STOR (put)====
Before an override for STOR is called, Janus FTP obtains the file
from the client and places it in temporary procedure 0.
It is the
responsibility of the override to take that procedure and store it.
<var>$Ftp_Get_Operand</var> returns the name of the procedure being stored.
To read procedure 0 for processing, you can use the Sirius
$functions <var>[[$Procopn]]</var>, <var>[[$Procget]]</var>, <var>[[$Proccls]]</var>, and <var>[[$Procdat]]</var>.
Below is a skeleton of a STOR override:
<p class="code">Begin
  VARIABLES ARE UNDEFINED
  %rc Float
  %buf String Len 255
&#42;  Loop on the lines in proc 0,
&#42;  which was loaded by the JANUS FTP Server.
  %rc = $procopn(0)
  %buf = $procget
  Repeat While ($Len(%buf))
&#42;      Do something with the
&#42;      data in %buf.  Perhaps store
&#42;      it in a file and use
&#42;      $Ftp_Get_Operand as a key.
        %buf = $procget
    End Repeat
&#42;  If the operation failed,
&#42;  send a failure indicator to
&#42;  the FTP client.
  If ( Some Failure Test ) Then
      %rc = $ftp_fail
  End If
End
</p>
====Overriding RETR (get)====
If you are writing an override for RETR, you must place any data you want
to send back to the FTP client in temporary procedure 0.
After the override commands
are executed, the contents of temporary procedure 0 are sent to the FTP client.
<var>$Ftp_Get_Operand</var> returns the name of the procedure being fetched.
To place the data in procedure 0, you may use one of the following techniques:
<ul>
<li>$Bldproc
<li>USE PROC 0
</ul>
</ul>
Below is a skeleton of a RETR override:
<p class="code">DELETE PROC 0
USE PROC 0
Begin
  VARIABLES ARE UNDEFINED
  %rc Float
&#42;  Find some records, maybe
&#42;  use $Ftp_Get_Operand in the criteria.
  For Each Record Where ....
&#42;    PRINT some info from
&#42;    the file.  Since USE is
&#42;    active, the lines will
&#42;    go to proc 0, which will
&#42;    be sent by JANUS FTP
&#42;    to the FTP client.
      Print whatever
  End For
&#42;  If the operation failed,
&#42;  send a failure indicator
&#42;  to the FTP client.
  If ( Some Failure Test ) Then
      %rc = $ftp_fail
  End If
End
</p>
====Overriding RNTO (rename)====
In a rename override, <var>$Ftp_Get_Operand</var> returns the new name of the procedure,
while <var>$Ftp_Get_Old_Name</var> returns the old name.
How this is implemented in the override is completely up to you.
There is no override for the RNFR command.
====Overriding DELE (delete)====
In a delete override, <var>$Ftp_Get_Operand</var> returns the name of the item to be deleted.
How this is implemented in the override is completely up to you.
====Overriding LIST (ls, dir)====
Like a RETR override, a LIST override must place the listing to be returned
in temporary procedure 0.
After the override commands
are executed, the contents of temporary procedure 0 are sent to the FTP client.
<var>$Ftp_Get_Operand</var> returns the wildcard pattern used to select file names, or
it returns the null string (zero length) if no file pattern was specified.
A LIST override must work in two modes:
<ul>
<li>Narrow mode (<var>$Ftp_Get_Command</var> returns <code>NLST</code>).
You must place a simple list of file names, one per line, in procedure 0.
<li>Wide mode (<var>$Ftp_Get_Command</var> returns <code>LIST</code>).
You must place a list of files, in UNIX <code>ls -l</code> format, in procedure 0.
</ul>
'''Note:''' If you are overriding LIST, take extreme care with formatting.
Many FTP clients parse LIST output and expect the exact <code>ls -l</code> format.
The client program may crash or produce odd results if the format it wrong.
==References==
The best place for detailed information about FTP is Internet RFC 959, which specifies the protocol.
This is available on the Internet ([http://www.ietf.org/rfc/rfc959.txt]).
In addition, there are a number of open source FTP clients and servers that one may examine.
They can be found using a search engine like <var class="product">Google</var>.


[[Category:Janus Sockets]]
[[Category:Janus Sockets]]
[[Category:Janus FTP Server]]

Latest revision as of 19:21, 29 May 2013

Janus FTP support allows you to set up one or more FTP servers within a Model 204 online. You use JANUS commands to define and start a TCP/IP listening port for each Janus FTP Server, and you use JANUS FTP commands to specify operating and access rules for each server. Janus FTP servers can then be accessed with the FTP client of your choice to copy procedures into and out of Model 204 procedure files.

The FTP client may be running on any platform that can make a TCP/IP connection to the online. Many tools such as code management systems and editors have built-in FTP clients which can now be used with Model 204 procedures and procedure files.

Janus FTP servers can peacefully coexist with any other FTP servers you may be running.

You must be licensed for Janus Sockets and Janus TCP/IP Base in order to use Janus FTP support.

This article provides an overview of the capabilities and features of Janus FTP Server support. The remaining topics that describe Janus FTP Server support are referenced in the "See also" section at the bottom of the page.

The best place for detailed information about FTP is Internet RFC 959, which specifies the protocol. In addition, there are a number of open source FTP clients and servers that one may examine. They can be found using a search engine like Google.

Feature summary

The following capabilities are provided by the Janus FTP Server.

  • Model 204 procedures may be downloaded to a local platform using any FTP client.
  • Model 204 procedures may be added, replaced, deleted, and renamed with any FTP client.
  • Procedure listings are supported (the FTP protocol LIST command). This permits GUI FTP clients such as WS_FTP and others to render lists of Model 204 procedures.
  • EBCDIC/ASCII translation in both directions is automatic and transparent for FTP ASCII text transfers.
  • Binary file transfers (FTP TYPE I are supported to permit transfer of binary files such as images (.JPG, .GIF, etc.) and Java applets (.class, .jar, etc.).
  • JANUS FTP commands are used to map the standard UNIX folder structure that FTP clients expect to Model 204 procedures and procedure files. Multiple Model 204 procedure files may be accessed from a single port with a Janus FTP server. This mapping effectively creates folders that can be navigated by FTP clients using the standard FTP cwd command (change working directory/folder). For more information, see "Folder mapping".
  • FTP user authentication is based on Model 204 user IDs and passwords. It automatically uses whatever security package (for example, RACF), that your online uses to authenticate logins.
  • Anonymous FTP is available. For security, anonymous FTP is off by default when an FTP Server is created with JANUS DEFINE. Extra syntax is required to enable anonymous FTP, which makes it impossible to accidentally enable it when you are creating an FTP server. For more information, see "Anonymous FTP".
  • Active and passive FTP are supported. Passive is more secure, and Sirius recommends using passive FTP where possible. However, some older and simpler FTP clients only work with active FTP (for example, the Windows command line FTP client). Passive FTP is considered "firewall friendly," since it does not require the FTP client to open up TCP/IP server sockets, which is commonly viewed as a security exposure, thus prevented by many firewalls.
  • All three operating systems are supported (MVS, VM, and VSE).
  • FTPS (SSL/TLS encrypted data transmission) is available as of Sirius Mods version 8.0.
  • Within an Online, you can run as many FTP servers as you want, using different port numbers for each. There is no requirement to use the default FTP port number (21). This lets you run another FTP server on the default FTP port and run Janus FTP servers on any other port numbers you want. However, it is desirable to use the default port when possible, since client software will have to be reconfigured otherwise. (By default, all FTP clients try to connect to port 21.)
  • For advanced applications, you can write "overrides" for FTP commands, where you provide a custom implementation for a command to perform application-specific processing. Overrides are written in User Language. A possible use of an override is to read and write records from a Model 204 file using FTP. For more information, see "Overriding FTP protocol commands".
  • You can use the procedure name suffix (for example, .HTML) to control the transfer mode of a file (text vs. binary). For more information, see JANUS FTP SUFFIX.

Key concepts

This section covers the key concepts to master to use the Janus FTP Server. It is vital to grasp these concepts before learning specific commands.

Folder mapping

The most important concept to understand when using the Janus FTP Server is the concept of folder mapping. FTP clients are typically designed to work with a UNIX-style file system, that is, a hierarchy of folders, where folder names are separated by forward slashes (/). Model 204 files are basically a flat list of procedures without any concept of hierarchy.

Janus FTP Server provides a command (JANUS FTP ASSIGN) that lets you create folders. Folders are referenced by an FTP client to locate procedures, which the FTP client sees as files. A folder is essentially a logical name an FTP client references as a UNIX-style folder.

Janus FTP Server also has the concept of a "current folder." A Janus FTP server returns the name of the current folder in response to the FTP PWD (print working directory) command. The current folder is where FTP operations such as get and put (RETR and STOR) look for the procedures referenced; it functions like a current directory or folder in UNIX or MS DOS.

When a folder is defined, it may be associated with a Model 204 file. A folder defined with a file can be the target of FTP get, put, rename, and delete operations, if the client user has appropriate permissions. Folders without files are legal. They can be used for modelling intermediate levels in a hierarchy, or they can be used in conjunction with overrides.

This level of indirection in the server lets FTP clients avoid storing procedure file names (the friendlier FTP clients remember server path information). This permits the system manager to switch procedure files without breaking users' FTP client setups. A user simply changes the folder mapping to point to the new procedure file.

Folder names

The names of FTP folders must obey the following syntax rules:

  • They begin with a forward slash (/), are 2 to 63 characters in length, and may not end with a slash.
  • They consist of groups of alphanumeric characters, separated by single forward slashes (in UNIX or URL style).
  • They may not contain consecutive slashes (//AA and /A//B are not permitted).
  • They are case insensitive.
  • They may not contain embedded blanks.

Examples of valid FTP folder names include:

/HOME /G/L/W /STOOGES /STOOGES/HOME

Prefixing

By default, a folder mapping is simply a way to connect a folder seen by the FTP client to a Model 204 file. However, the prefixing option permits the folder name to be automatically made part of the procedure name in a manner transparent to the FTP client. Prefixing is off by default, but it can be enabled using the PREFIX parameter on the JANUS FTP ASSIGN command.

Prefixing a folder has the characteristics listed below. In the examples, assume /STOOGES is a folder with prefixing turned on, and MOE and LARRY are procedure or file names.

  • Procedures/files stored in a prefixed folder are stored with the procedure name prefixed with the folder name. For example, MOE is stored as /STOOGES/MOE.
  • When an FTP client asks to fetch a procedure, the FTP Server looks for it by prefixing its name with the folder name. For example, if the FTP client asks for LARRY, the server searches for /STOOGES/LARRY.
  • On requests for folder listings (FTP LIST command), only those procedures whose names are prefixed with the folder name are returned. For example, /STOOGES/MOE and /STOOGES/LARRY are listed, but the procedures FOO and /JETSONS/GEORGE are not.
  • Mapping several folders that have prefixing enabled to one procedure file lets you segregate work by developer within one procedure file. Since security for Janus FTP is administered at the folder level, it can easily be set up so that each developer can only update their own files.
  • Normally, the folder name is used as a prefix with its slash (/) or slashes, and a slash separates the folder from the file name. However, optionally, a period can be used to replace all such slashes (for example, /STOOGES/MOE becomes .STOOGES.MOE).

    Note: This replacement is only done internally: the FTP clients see only the slashes.

Folder security

FTP folder access rights are granted to one or more users in either of the following ways:

  • When a folder is created with JANUS FTP ASSIGN, default access rights for all users (not including anonymous access) may be assigned.
  • A user, user group, all users (except anonymous), or the anonymous user may be given access rights to a folder using JANUS FTP ALLOW.

In addition, either of these types of access to the folder may be granted to the user or users given access:

READ FTP get (RETR command) and directory listings are permitted. Also, the FTP client or user can change directory (FTP protocol CWD command) into this directory.
WRITE READ privileges plus permission for FTP put, delete, and rename (STOR, DEL, RNFR, and RNTO).

A user other than the anonymous user might be granted access rights from more than one source:

  • He or she might be granted access explicitly with JANUS FTP ALLOW.
  • He or she might be a member of one or more groups granted access with JANUS FTP ALLOW.
  • JANUS FTP ALLOW might be specified with ALL.
  • The folder might have its default access set by JANUS FTP ASSIGN with DEFAULTPRIVS.

If multiple sources are granting access, the user is granted the highest access specified by any of the sources giving the user access. (The access rights are aggregated.)

Home folders

Much like UNIX and other folder-tree based systems, FTP has the concept of a home folder location, where the user is placed after successfully connecting to and logging in to the FTP server. Janus FTP Server implements this concept with a JANUS command (JANUS FTP HOME) that permits setting up a home folder for a user, a group of users, all users (excluding anonymous), or the anonymous user.

A user must have a home folder specified, or FTP login is rejected. In addition, the user must have at least READ privileges for the folder specified as their home folder. This is checked at login; a login is rejected if the user does not have at least READ access to their home folder.

The root folder ( / )

In UNIX systems, the root folder is indicated by a forward slash (/). In Janus FTP Server, you may not define this folder; it is automatically defined for you. If you navigate (change directory) to folder "/" in your FTP client, you see a list of all first-level folders. First-level folders are those that have only one part (for example, /STOOGES, /JETSONS).

Anonymous FTP

Within the context of Janus FTP Server, anonymous FTP is defined as FTP access that does not require a valid Model 204 user ID. Off by default when an FTP server is created, anonymous access is enabled by the ANONYMOUS parameter on JANUS DEFINE.

By default, anonymous access is achieved by connecting as user anonymous, but you can change that value with the JANUS DEFINE command. An anonymous user's password is not verified.

Command overview

A detailed reference of the Janus commands that pertain to FTP servers is presented in "Janus FTP Server command reference". The following overview is intended to introduce the commands and make it easier to understand the examples in "Janus FTP Server examples".

JANUS DEFINE name num FTPSERVER ...
Creates FTP servers in the online.
JANUS FTP ASSIGN
Creates FTP folders and maps them to Model 204 files, as described in "Folder mapping".
JANUS FTP DEASSIGN
Removes FTP folders.
JANUS FTP ALLOW
Grants read or write access to a folder created with JANUS FTP ASSIGN.
JANUS FTP DISALLOW
Revokes read or write access to a folder.
JANUS FTP HOME
Specifies a home folder (initial location at login) for a user. Once connected and logged in, a user may navigate to folders to which they have been granted at least read access.
JANUS FTP ON
Sets up overrides, by specifying files to be opened and commands to be executed when a specific FTP operation is performed.
JANUS FTP SUFFIX
Allows specification of the transfer mode (text or binary) of procedures/files by suffix (for example, .html, .xml).
JANUS DISPLAYSOCK
Displays a report of the rules created with FTP ASSIGN, FTP ALLOW, FTP HOME, FTP ON, and FTP SUFFIX if executed for an FTPSERVER port.

Socket and procedure handling

This section provides notes about how Janus FTP Server works with sockets and Model 204 procedures.

Sockets

  • The Janus FTP Server is implemented as a special type of Janus server socket. Consequently, the JANUS SRVSOCK command may be used to control access to an FTP Server.
  • When an FTP Server performs active mode file transfers, it opens a client TCP/IP socket back to a server socket that the FTP client opens. If you want to enable active file transfers, you must set up a Janus CLSOCK socket that the FTP server can use. See JANUS DEFINE for more information. This lets you have additional security controls: you may place whatever restrictions you like on the client socket based on your site's security policies. A useful way to think about the difference between active and passive file transfer mode is the following:
    • In passive mode, FTP is a true client/server protocol where the server only opens server sockets and the client only opens client sockets.
    • In active mode, FTP is more like a peer-to-peer protocol where both the client and server open both client and server sockets.

The example in "FTP client and server interaction" contains a small demonstration of passive FTP socket handling.

Procedures

  • When a procedure is renamed via FTP, the standard Model 204 rename operation is performed. This leaves the old name as an alias. While this is not standard FTP behaviour, it is the standard way rename operations work in Model 204.
  • When a binary file (for example, a .jpg file) is uploaded by the Janus FTP Server in binary transfer mode, it is stored in standard base64 binary format. Procedures that were stored by Janus Web Server in either binary or base64 format may be retrieved using Janus FTP Server.
  • All uploaded files are copied into CCATEMP. This way, if a network or browser problem prevents the entire file from being transferred, the request can be discarded without a risk of leaving partial data in a procedure. Once all the data from a request has been received into Model 204, the file is simply copied into the target procedure, perhaps being converted to the base64 format if the file consists of non-text data. When a procedure is being updated, Janus FTP attempts to get an exclusive lock on the procedure before doing the update. If it is unable to obtain an exclusive procedure lock, the request fails. The exclusive lock is only held while data is copied from CCATEMP to the procedure. This means the following:
    1. Once the copy operation starts, it completes regardless of the status of the network connection; there is no risk of leaving behind a partial procedure.
    2. The exclusive lock on a procedure is generally held very briefly (typically a few milliseconds), so it is not likely to disrupt a download for the same procedure.
    3. This is a simple "last-to-save, wins" approach, and it offers no update management for the procedure file.

Security and Janus FTP Server

A very security-centric approach is taken in the design of the Janus FTP Server. This is seen in the following characteristics:

  • There is no FTP access at all unless a JANUS DEFINE command to create an FTP server is issued.
  • No procedure file is available to FTP unless FTP access to it is specifically granted (using FTP ASSIGN and FTP ALLOW).
  • By default, there is no anonymous access to Janus FTP servers.
  • The ALL option on FTP ALLOW and the DEFAULTPRIVS option on FTP ASSIGN do not include anonymous access. Anonymous access must always be explicitly granted.
  • Since active FTP is widely viewed as less secure, you can create an FTP (passive) server that does not permit active connections. To create a passive server, simply do not specify the CLIENTSOCKET parameter on the JANUS DEFINE command for the FTP server. Without CLIENTSOCKET, only passive data transfers are enabled.
  • SSL (Secure Sockets Layer) data transmission is supported (as of Sirius Mods version 8.0). Set by the JANUS DEFINE SSL parameter (or both the SSL and SSLOPT parameters), only explicit invocation of SSL/TLS is supported for FTPSERVER ports, as described at the Wikipedia FTPS entry.

FTP features not currently supported

The following FTP features are not currently supported by Janus FTP. They will be considered for possible future releases.

  • Restart of aborted transfers
  • Client side directory/folder manipulation with mkdir and rmdir (MKD and RMD)

Supported FTP protocol commands

FTP is essentially a command response protocol, where a server responds to text commands. The FTP protocol specifies a set of commands to which a server must respond. Janus FTP support implements the following FTP protocol commands:

  • USER and PASS, to process logins.
  • QUIT, to end a session gracefully.
  • PORT, to initiate active transfers.
  • SYST, to respond to system type queries. Many FTP clients send SYST to probe the FTP server type. Janus FTP answers UNIX, then emulates a UNIX-style FTP server. This works with all FTP clients, since they all support UNIX. If Janus FTP answered VM/MVS/VSE, many FTP clients would not work.
  • TYPE, to select between BINARY and ASCII (text) transfers.
  • PASV, to initiate passive transfers.
  • PWD/XPWD, to return the working directory/folder.
  • CWD/CDUP, to change folders.
  • RNFR/RNTO, to do renames.
  • STOR, to store/put/upload files.
  • RETR, to get/fetch/download files.
  • DELE, to delete files.
  • LIST/NLST, to get folder/directory listings.
  • AUTH, to invoke SSL/TLS encrypted transmissions (as of Sirius Mods version 8.0).

Note: The syntax of these commands is not the same as that of the more or less standard command line FTP clients, nor is there an exact one-to-one correspondence between the command sets. An FTP client constructs these commands "under the covers" to communicate with the FTP server.

See also

The following topics complete the description of Janus FTP Server support:

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=Janus_FTP_Server&oldid=59948"