Janus FTP Server: Difference between revisions

Revision as of 23:11, 17 February 2012

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 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).
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, below, 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 was 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.

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)
SSL (Secure Sockets Layer) data transmission

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.

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.