The RegisterProgram method registers an executable program
for use with the SITE EXEC command. Because this can present a
significant security risk to the server, clients are not given
permission to use this command by default. A client must be explicitly
granted permission to use SITE EXEC by including ftpAccessExecute
as one of the permissions when authenticating the client session with
the Authenticate method or creating a virtual user using the
AddUser method.
To give the server complete control over what programs can be
executed using SITE EXEC, the program must be registered with the
server and referenced by an alias specified by the CommandName
parameter. The maximum length of a program name is 31 characters and
it must be at least 3 characters in length. The name must only consist
of alphanumeric characters and the first character of the program name
cannot be numeric. The program name is not case-sensitive, however
convention is to use upper-case characters. If a program name is
specified that already has been registered, it will be updated with
the new information provided by this method.
The ProgramFile string specifies file name of the
program that will be executed. You should not install any executable
programs in the server root directory or its subdirectories. A client
should never have the ability to directly access the executable file itself. It
is permitted to have multiple command names that reference the
same executable file. The only requirement is that the command names
be unique. The program name may contain environment variables
surrounded by % symbols. For example, %ProgramFiles% would be expanded
to the C:\Program Files folder.
It is important to note that the program specified by ProgramFile
must be an executable file, not a script or batch file. If the program
name does not contain a directory path, then the standard Windows pathing
rules will be used when searching for an executable file that matches the
given name. It is recommended that you always provide a full path to the
executable file.
The Parameters string is used to define optional command
line parameters that will be included with the command. This string
can contain placeholders that are replaced by additional parameters
specified by the client when it sends the SITE EXEC command. First
replacement parameter is %1, the second is %2 and so on.
The executable program that is registered using this method must
be a console application that writes to standard output. Programs that
write directly to a console, or programs written to use a Windows user
interface are not supported and will yield unpredictable results. In
most cases, those programs that do not use standard input and output
will be forcibly terminated by the server. If the program attempts to
read from standard input, it will immediately encounter an end-of-file
condition. Programs executed by the SITE EXEC command have no input;
it is similar to a program that has its input redirected from the NUL:
device. If the program must process a file on the server, the local file
name should be passed as a command line parameter.
The output from the program will be redirected back to the client
control channel. The output should be textual, with each line of text
terminated by a carriage return and linefeed (CRLF). Programs that
write binary data to standard output, particular data with embedded
nulls, will yield unpredictable results and are not supported. To
ensure that the program output conforms to the protocol standard, any
non-printable characters will be replaced with a space and each line
of output will be prefixed by a single space.
If the server is running on a system with User Account Control
(UAC) enabled and does not have elevated privileges, do not register a
program that requires elevated privileges or has a manifest that
specifies the requestedExecutionLevel as requiring administrative
privileges.