In Brief: Used to send a file upload item via secure SFTP.
Important Notes: RackForms does not currently support standard FTP connections, as they are unencrypted and inherently insecure. Thus, only SFTP connections are supported.
RackForms cannot create directories with this FTP module, only write to
Generally speaking the S/FTP module has three modes of operation:
Flat Files In this mode we simply enter a file path and name into the Flat File Name field. So long as this file exists RackForms will send it upon submission.
Dynamic Flat Files In this mode we've generally taken the result of a form submission and created a flat file based on the user input to the form. A good example of this is an XML or text file. The secret sauce is in order to send a dynamic file we must first create it, which is why in this mode the S/FTP module will be used after a Flat File module call. The Flat File module creates the file, this module sends it to the FTP server.
Send Uploaded File In this last mode we'll take the result of a file upload and send it to the FTP server. The critical component here is telling RackForms which file field we want to send. We so this in the File Upload Field Name field.
Generally enabled, though can be useful to temporarily disable this feature during testing and development.
When enabled, displays debug and information data on your connection and transfer.
Not used at the moment.
The server you wish to connect to. Can be a local machine, such as localhost, or a remote IP or host name.
For most S/FTP connections this should be 22.
The login name for the S/FTP user.
The password for the S/FTP user.
The directory we wish to upload our file to. Can be blank, in which case the login users home/root directory will be used. If not blank that directory must exist on the system.
In almost all cases a value used here must start with the root directory name, and then with a /.
For example, to save to the path:
In addition to uploading file upload and pdf templates we can also simply upload a local file from your server. In most cases this will be a file we've created dynamically via the Flat File module, but can also could be any file the server has access to.
To support dynamic file selection this field is accepts tokens, meaning we can can create the file name based on form input or any other dynamic text values we like. Because of this and as noted in the Editor, extreme caution must be used here!
Allowing users the ability to name files means that user could, in theory, create a file that performs some untrusted operation on the machine. If this file is accessible to the web directory, a user could, in theory, call up that file from the browser the same as any other PHP page. Because of this RackForms outright prevents files with the .php extension from being saved, but depending on your operating system many other file types may be callable.
The following guidelines should help mitigate the most common issues, but even this may not be a fully comprehensive list for your environment and security needs. If unsure, do not use dynamic file names!
The theme of the list above is to define the following: Uploading files to a server is always a risky proposition: doing so while possibly allowing untrusted users control of the file name is a massively dangerous operation when we're unsure of the security implications.
In summary do not use custom file names for untrusted users, and if we do, make sure the files being uploaded are non-executable and saved to a safe location.
If we understand the security implications the power of this module is in its ability to
pluck a freshly generated file from the file system and send it to the FTP server.
Critically, this file can have a dynamic name, which means we can create a unique file name
for each form submission. For example, assuming we had a form
field with the name of
Name, we could enter a value in the format of:
This will generate a file on the FTP end in the form of:
For upload field transfers this field must contain the valid Name/Value of the file upload field we wish to send. We can assign a custom name to this item in the destination FTP folder via the next property, File Upload Name.
As an alternative to file uploads, when left blank this field will attempt to send any PDF template pages this job contains.
To create a PDF template page, create a standard form page and under its Page PDF Output Properties options set PDF Output Mode to: Save for Email / SFTP Output.
Please note the two modes, file upload and PDF template, cannot be used in the same item. If we wish to use both, create two separate SFTP items, one with this field blank, the other with the name of the field we wish to process.
The name we'll assign to the uploaded file on the destination FTP server. By default it's left blank, in which case the file name of the original uploaded item is used or if using PDF templates, the name of the form page. However, we can use tokens in this slot, such as a text field of the name text1 as:
This will take the value a form user typed into that text field, minus and periods or forward/back slashes, and use that as the file name. Care must be taken here however, as this value alone will usually not create a desirable file name, as the value won't typically include a file extension.
For this reason we can also use the hard-coded value FILENAME to insert the original file name. Taken together, we can append a dynamic value to the start of the original file name using:
The FILENAME property is important as our upload files should usually contain a file extension. However, we have one other hard-coded value we can use, EXT, which will resolve to just the extension of the original file. For example, to create a file name of a dynamic text field, the text value OFFICIAL, followed by the original files extension, we would use: