JANUS FTP

From m204wiki
Revision as of 18:00, 16 April 2013 by JAL (talk | contribs) (→‎Syntax)
Jump to navigation Jump to search

Configure Janus FTP Server

The JANUS FTP command defines the rules for a Janus FTP Server running on a Janus Sockets FTP (FTPSERVER) port. These rules primarily control access to the files exposed by the FTP server.

Syntax

JANUS FTP portname rule_type other_parameters

The first two parameters are positional and are required:

portname 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 FTPSERVER parameter.
rule_type The rule_type specifies the sort of rule being specified for the port(s). Valid values for rule_type are:
ASSIGN Creates FTP folders and maps them to Model 204 files.
DEASSIGN Removes FTP folders.
ALLOW Grants read or write access to a folder created with JANUS FTP ASSIGN.
DISALLOW Revokes read or write access to a folder.
HOME Specifies a home folder (initial location at login) for a user.
ON Sets up overrides, by specifying files to be opened and commands to be executed when a specific FTP operation is performed.
SUFFIX Allows specification of the transfer mode (text or binary) of procedures/files by suffix (for example, .html, .xml).
other_ parameters The additional parameters allowed for the JANUS FTP command depend on the rule_type that is specified. The various forms of rule_type and their parameters are described in the following alphabetically ordered sections.

You must specify at least three JANUS FTP commands — one each of JANUS FTP ASSIGN, JANUS FTP ALLOW, and JANUS FTP HOME — and it typically takes a set of JANUS FTP 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 JANUS FTP commands to issue is ASSIGN.

For more examples and more information about Janus FTP Server support, see Janus FTP Server.

Rule types

JANUS FTP ALLOW

This command is used to grant user access to a folder in addition to any access granted via a DEFAULTPRIVS parameter on the JANUS FTP ASSIGN for the server port.

Syntax

JANUS FTP portname ALLOW foldername READ | WRITE - TO [USER user] | [USGROUP usgroup] | ANONYMOUS | ALL


Where:

portname Must be a previously defined Janus FTP Server port.
foldername A folder previously created with JANUS FTP ASSIGN.
READ or WRITE The folder access privileges being granted. One of these must be specified:
READ FTP get (RETR command) and directory listings (LIST) are permitted. Also, the FTP client or user can cd (change directory, CWD) into this directory.
WRITE READ privileges plus permission for FTP put, delete, and rename (STOR, DEL, RNFR, and RNTO).
TO To whom access is being granted to foldername. One of these options must be specified, and only one of these per folder may be issued. To modify an earlier ALLOW rule, first use FTP DISALLOW.
USER user A Model 204 user ID. The user is not checked for existence when this command is issued.
USRGROUP usrgroup A user group created with the JANUS DEFINEUSGROUP. The group is not checked for existence when this command is issued.
ANONYMOUS Anonymous users (Model 204 user ID not required).
ALL All Model 204 users (except the anonymous user).

Examples of valid FTP ALLOW commands follow:

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


For more information about folder access, see "Janus FTP Server 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”.

Syntax

JANUS FTP portname ASSIGN foldername - [ TO FILE filename ] - [ DEFAULTPRIVS READ | WRITE ] - [ PREFIX [. | /] ]

Where:

portname Must be a previously defined Janus FTP Server port.
foldername The name of the FTP folder being created. For more information about naming rules, see "Janus FTP folder names"
TO FILE filename The Model 204 procedure file being associated with foldername.
DEFAULTPRIVS The privileges a user gets unless a JANUS FTP ALLOW rule gives them greater access. If DEFAULTPRIVS is not specified, no access is permitted except that granted by ALLOW rules. Default privileges do not apply to anonymous access. Any anonymous access must be granted with an ALLOW rule. The privileges allowed are READ and WRITE, one of which must be specified, as discussed in ALLOW.
PREFIX Invokes prefixing for this folder, as described in "Janus FTP Server prefixing". Files uploaded to this folder by FTP clients are stored with the name of the folder prefixed to the filename. File MYFILE uploaded to folder ANNUAL becomes procedure /ANNUAL/MYFILE. PREFIX may be be followed by a "prefix character" — forward slash ( / ) or period (.) — which is used as the separator in folder names. The default is a forward slash. NB: The characters in the prefix string are added to and do increase the length of the procedure name, whose Model 204 limit is 255.

You can dynamically assign folders once a port is started, but you may not issue multiple JANUS FTP ASSIGN commands for the same folder. To reassign a folder, you must first remove the assignment using JANUS FTP DEASSIGN. You may not deassign a folder once a port is started, however; in this case, you must first drain the folder using the JANUS DRAIN command.

If you use a single JANUS FTP ASSIGN to create a folder such as /A/B/C, the following FTP change directory command works as expected:

cd /A/B/C

However, you cannot use cd to move to the intermediate folder levels /A and /A/B, unless each of these levels is also defined with an individual JANUS FTP ASSIGN command. In addition to defining /A, /A/B, and /A/B/C as three separate folders with three ASSIGN commands, allowing navigation to all three levels also requires granting at least READ access at each level. The following statements create this three-level folder structure:

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

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:

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

As a result:

  • 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 INFO file uploaded to folder /A/B/C is stored as /A/B/C/INFO.
  • To clients, a display of the list of the files in any folder contains only the files that are prefixed with that folder name.
    Note: Such a display may also include files that belong to a subfolder: for example, the /A/B/C/INFO file will be displayed in a list of the files in folder /A as /A/B/C/INFO, in a list of the files in folder B/ as /B/C/INFO, and in a list of the files in folder C/ as /C/INFO.

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:

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

Of course, in all the examples above, you can use FTP ALLOW commands (along with or in place of the DEFAULTPRIVS parameter of FTP ASSIGN) to diversify user access. For example:

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

A benefit of predefining a folder tree like /A, /A/B, and /A/B/C 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. Janus FTP Server 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.

Syntax

JANUS FTP portname DEASSIGN foldername

Where:

portname Must be a previously defined Janus FTP Server port.
foldername A folder previously created with JANUS FTP ASSIGN.

Once an FTP Server port is started, no JANUS FTP DEASSIGN commands may be issued for it; the port must first be drained (using JANUS DRAIN).

A folder may not be removed with DEASSIGN if it is referred to by JANUS FTP ALLOW, JANUS FTP HOME, or JANUS FTP ON rules.

Example DEASSIGN commands follow:

JANUS FTP FTP04 DEASSIGN /TEMPAREA JANUS FTP FTPANON DEASSIGN /JUNK

JANUS FTP DISALLOW

This command revokes folder access rights that were previously granted using JANUS FTP ALLOW.

Syntax

JANUS FTP portname DISALLOW foldername - TO [USER user] | [USGROUP usgroup] | ANONYMOUS | ALL

Where:

portname Must be a previously defined Janus FTP Server port.
foldername A folder previously created with JANUS FTP ASSIGN.
TO Specifies whose access to foldername is to be taken away. Users not previously specified by JANUS FTP ALLOW are ignored. One of these options must be specified:
USER user A Model 204 user ID. The user is not checked for existence when this command is issued.
USRGROUP usrgroup A user group created with the JANUS DEFINEUSGROUP command. The group is not checked for existence when this command is issued.
ANONYMOUS Anonymous users.
ALL All Model 204 users (except an anonymous user).

An example DISALLOW command follows:

JANUS FTP FTP01 DISALLOW /PUB0 TO USER XXXX

JANUS FTP HOME

This command identifies the folder where an FTP user is placed when they log in.

Syntax

JANUS FTP portname HOME foldername - TO [USER user] | [USGROUP usgroup] | ANONYMOUS | ALL

Where:

portname Must be a previously defined Janus FTP Server port.
foldername A folder previously created with JANUS FTP ASSIGN.
TO The TO clause identifies for whom a home folder is to be set up. One of these options must be specified:
USER user A Model 204 user ID. The user is not checked for existence when this command is issued.
USRGROUP usrgroup A user group created with the JANUS DEFUSG command. The group is not checked for existence when this command is issued.
ANONYMOUS Anonymous users (Model 204 user ID not required).
ALL All Model 204 users (except the anonymous user).

Note: All Janus FTP Server users must have a home folder assigned.

When a user logs in, the JANUS FTP HOME 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:

  1. If the user is anonymous and there is an anonymous entry, use it; but if there is no anonymous entry, reject the login.
  2. If the user is not anonymous, do the following:
    1. If an HOME rule specifies the user on a USER clause, use that folder.
    2. If no USER clause matches, but the user is in a group specified in an HOME rule USGROUP, use that folder.
    3. If no USGROUP group contains the user, but an ALL rule is present, use that folder.
    4. If no HOME rule matches, the login is rejected.

Example JANUS FTP HOME commands follow:

JANUS FTP FTP01 HOME /GLW2HOME TO USER GLW2 JANUS FTP FTP01 HOME /ALL TO ALL JANUS FTP FTP01 HOME /GLWHOME TO USGROUP FTP

JANUS FTP ON

This command lets you override the default processing of an FTP operation (service command) with your own version.

Syntax

JANUS FTP portname ON foldername | * - STOR | RETR | LIST | RNTO | DELE - [OPEN fg [[AND fg] ...]] CMD cmd [[AND cmd] ...] | DEFAULT

Where:

portname Must be a previously defined Janus FTP Server port.
foldername A folder previously created with JANUS FTP ASSIGN. If an asterisk (*) is specified instead of a folder name, the override is used for all folders on the port.
STOR | RETR | LIST | RNTO | DELE Names the operation being overriden (one of the following must be selected). For a list of all the FTP commands supported by Janus FTP Server, including those not available for override, see "Janus FTP Server command reference".
This option Overrides this operation
STORFTP put (upload files)
RETRFTP get (download files)
LISTFTP ls or dir (list files in wide or narrow format)
RNTOFTP rename
DELEFTP delete
OPEN fg Lists one or more files or groups to open before the commands specified on the CMD clause are run. If you specify multiple files or groups, they must be separated by AND keywords. Each fg term has the following format, where you can specify individual open privileges (which default to X'0221'):

[FILE | GROUP] fgname [[WITH] privs]

CMD cmd Lists one or more Model 204 commands to execute to perform the override. If more than one is specified, they must be separated by AND 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.
DEFAULT Resets any previous FTP ON for the folder, restoring the default handling of the operation specified in that ON rule. In short, to reverse an ON, use DEFAULT.

Note: For a given operation and folder, any previous ON rule must be be turned off with DEFAULT before a new FTP ON is issued.

Example FTP ON commands follow:

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'

JANUS FTP SUFFIX

This command lets you specify any file types that a Janus FTP Server 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.

Syntax

JANUS FTP portname SUFFIX suffix [TEXT | DEFAULT]

Where:

portname Must be a previously defined Janus FTP Server port.
suffix A file-type suffix that ends a procedure name (preceded by a period in the procedure name). For example, you use HTML to match procedures whose names are of form WHATEVER.HTML.
TEXT Procedures with names ending in suffix will be handled as text data (not binary), even if the FTP transfer mode is BINARY.
DEFAULT Restores the default behaviour (no special handling); can be used to turn off a previously issued FTP SUFFIX command.

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.

Janus FTP Server uses base64 encoded format to store files that are uploaded (FTP put or stor) in BINARY FTP mode (type I). The FTP SUFFIX command is used to prevent text file types from being stored in base64.

Janus file storage formats are described further in the Janus Web Server documentation.

Example FTP SUFFIX commands follow:

JANUS FTP FTP01 SUFFIX HTML TEXT JANUS FTP FTP01 SUFFIX XML TEXT JANUS FTP FTP01 SUFFIX FOO DEFAULT

See also