Version 82, last updated by Xander Jansen at December 12, 2011 11:40 UTC

Administrator reference manual

This is the Administrator Reference Manual for FileSender version 1.0 and 1.1

Administering FileSender
Authentication
- IDP Attributes
Security considerations
- Warning - Encryption
Customization
Configuration
- Configuration file directives

Administering FileSender

Installation and initial configuration

Consult the relevant installation guide:

Regular tasks

Make sure the daily expiry cron job runs. This is needed to delete files and vouchers that have expired. The debian and RPM packages will install a daily cronjob for you in /etc.cron.daily/filesender. When installed from source make sure you have installed a cronjob as per the Configure cron section in the Installation Guide.
Clean temp_filestore and log directories. FileSender does not do any of this automatically so you as a server admin need to ensure this happens. The temp_filestore tends to get filled with files that are leftover when a user cancels an upload. Log files are created on a daily basis but are not automatically purged.
Check logfiles for errors.
Database cleanup: every upload to FileSender results in one or more database entries. Not all of these are deleted which could lead to performance degradation in the long run. You should check your database what the situation is and whether it needs cleanup of very old entries.

The Administrator web interface

The administrator web interface is accessed through the regular FileSender Flash UI. A button becomes visible when you log on with an account that has a GUID (like eduPersonTargetedId or ePPN) configured in $config['admin']. The administrator web interface provides an easy overview of the use of your FileSender installation.

Troubleshooting

Relevant logfiles to check

Relevant logging can appear at three places:

the FileSender logdirectory as configured in your config file with $config['log_location']
your webserver logs
your PHP logs (as per the relevant php.ini settings, often your /var/log/messages or /var/log/syslog file)

! If there is no logging in your FileSender log directory, make sure the web server can write to it.

! If nothing works you might have issues with connecting to your database. Increase database logging to study interaction between your database and FileSender.

Getting more debugging information

In case of problems you can turn on debugging in the FileSender configuration (see Debug settings for the relevant directives). Setting $config['debug'] = true will turn on extra logging (both for FileSender in the FileSender log-directory and PHP) and additionally will show some extra technical information in the Flash UI shown to the user.

To investigate client (the browser/Flash UI) problems (for a specific user) you can enable client specific logging by setting $config["client_specific_logging"] = true. By default this will generate extra logfiles per user for all users in the FileSender log directory with details about the relevant actions taken by the client. You can restrict the client specific logging to specific clients by specifying a GUID or Voucher ID with the $config["client_specific_logging_uids"] directive.

Note that turning on the debug settings will decrease performance so don't forget to turn off the debugging after investigation.

Authentication

FileSender has no local user database for user authentication but uses the SimpleSAMLphp software to have the authentication part handled by remote Identity Providers (IdP). In this model FileSender is the Service Provider (SP). The user is directed to the login page of the IdP and after succesful authentication an OK and a set of attributes is returned from the IdP to FileSender. The default installation and configuration has the Feide OpenIDP configured as public Identity Provider. If you want to connect your FileSender instance to your own (set of) Identy Provider(s) or Federation please have a look at the SimpleSAML Service Provider Quickstart.

IDP Attributes

FileSender is by default looking for the attributes 'mail' and 'cn' and 'eduPersonTargetedID'.

These are configurable in config.php in the SAML attribute settings section

You can check which attributes are received by your FileSender installation on the SimpleSAMLphp pages, in most cases that will be at https://<your-server>/simplesaml/module.php/core/authenticate.php . Login from that page to get a list of known attributes and their names and values.

Security considerations

Warning - Encryption

FileSender itself does not offer protection agains eavesdropping on the contents of uploaded/downloaded files.

Sensitive files can currently be protected in two ways:

in flight: protect files during upload/download using SSL. Ensure your FileSender webserver is only reachable over HTTPS.
in rest: files stored on the FileSender server should be encrypted by the user before uploading them.

Customization

FileSender offers some limited support for customization. Customatizations not mentioned in this section will require changing the code and will not survive upgrades or re-installs unless you keep a good backup of all your modifications.

Custom banner

By default FileSender will use the banner image supplied in the www/banner.png file to display at the top of all web pages. You can put a custom banner image in config/banner.png which will override the default banner image. This image has to be in PNG format and should be sized as 800x60 pixels.

Custom User Interface and instance name

The $config['site_name'] setting can be used to give your FileSender instance a custom 'friendly' name. The text in this directive will be used on the main login page and in the Subject: line and text body of all email messages.

The $config['site_splashtext'] can be used to display a custom text on the main login page. This text can contain HTML-code to insert links or do some simple formatting.

Both settings can be found in the General settings section of the configuration file.

Also have a look at the User Interface (UI) settings section for some settings to tweak the UI.

Custom Terms and Conditions (AUP)

Local Terms and Conditions (a.k.a. the Acceptable Use Policy) can be specified with the directives in the Acceptable Use Policy (AUP) settings section.

Custom support pages

The settings in the Support links section of the configuration file can be used to direct people to custom help and about pages and a page about the Gears plugin (version 1.0) or HTML5 support (version 1.1), i.e. the pages linked to the 'Help', 'About' and 'Gears'/'HTML5' links in the main user interface.

If you need custom help/about pages copy the default help.php and about.php to for example 'local-help.php' and 'local-about.php' and modify these copies. Then adjust the Support links settings to point to these custom pages. You can also just point to 'external' pages on for example your main website.

Modifying the supplied help.php and about.php is discouraged since these files in general will be overwritten with upgrades or re-installs.

The $config['site_logouturl'] setting (in the Site URL settings section) can be used to point to a custom page to return to after the authenticated user has logged out. Note that the actual use of this page also depends on the Identity Provider and/or Federation of the authenticated user, not all of them redirect back to the requested logout page.

Customising SimpleSAMLphp

In case you use the local SimpleSAMLphp 'Identity Provider' selection page you can have a look at the themefilesender module. This module will give SimpleSAMLphp the same look&feel as FileSender.

Language

FileSender 1.0 only supports one language (English). Full localisation (multi-language support) is on the road map for 2.0.

Configuration

All configuration of FileSender is done by editing the configuration file:

config/config.php

This file is actual PHP code so be careful to adhere to the PHP syntax:

keep the closing ; at the end of a $config specification
enclose string/text values in single or double quotes
boolean values can be specified as true or false (without quotes)
remarks/comments start with // or are enclosed in /* ... */

Configuration file directives

This section describes all the available configuration settings in config.php.

General settings

$config['admin']

description: list of UIDs of administrators, separated by comma. Administrators have access to the Administrator Interface. A UID is the value of the attribute defined in $config['saml_uid_attribute'] in the SAML attribute settings section.

default: none

example: '31a7bf626eb4fa2d425f611c0490940e71e1c42c' (with eduPersonTargetedID as UID attribute)

example: 'john.doe@mysite.dom' (with mail as UID attribute)

$config['adminEmail']

description: Email address(es, separated by ,) to receive administrative messages (low disk space warning)

default: none

$config['Default_TimeZone']

description: Set this to your local timezone according to timezone specifications in http://php.net/manual/en/timezones.php

default: 'Australia/Sydney'

example: 'Europe/Berlin'

$config['site_name']

description: Friendly name used for your FileSender instance. Used on the main login page and in emails.

default: 'FileSender'

example: 'AARnet CloudStor'

$config["site_splashtext"]

description: text to display on the main login page

default: "FileSender is a secure way to share large files with anyone! Logon to upload your files or invite people to send you a file."

remark: It is possible to use some simple HTML markup

User Interface (UI) settings

$config['datedisplayformat']

description: Format for displaying date/time. Format has to be specified in the Flex DateFormatter format specifier syntax

default: "DD-MM-YYYY"

example: "DD-MM-YYYY H:NN"

$config["versionNumber"]

description: show FileSender version number in the upper right corner

values: true/false

default: true

$config['site_showStats']

description: show upload/download statistics up in the upper right corner.

default: false

$config['displayUserName']

description: show 'Welcome user' in the upper left corner. The friendly name of the authenticated user is taken from the SAML attribute as specified by $config['saml_name_attribute'] or will be 'Guest' for users using a voucher.

values: true/false

default: true

Debug settings

$config["debug"]

description: if set to true server side logging will be more verbose and the UI wil display extra technical information of what's happening. This setting also increases the PHP loglevel.

values: true/false

default: false (true in beta releases)

$config['dnslookup']

description: if set to true the logging includes a reverse DNS lookup of the originating IP-address of the user. On really busy servers this may impact performance.

default: true

values: true/false

$config["client_specific_logging"]

description: turn on/off client specific logging. If set to true the client (Flash UI) will send debug information to the server which will be logged in separate user-specific files in the 'log_location' directory.

remark: turning on client specific logging will impact performance

default: false (true in beta releases)

values: true/false

$config["client_specific_logging_uids"]

description: A list of UIDs, separated by comma. When client specfiic logging is turned on the logging will be restricted to the UIDs in this list. The value "" (default) means 'log all clients'. A UID can be the UID of an authenticated user (as specified by the saml_uid_attribute setting below) or a voucher ID.

default: ""

example: '31a7bf626eb4fa2d425f611c0490940e71e1c42c, 6B30BA68-B883-8565-36B5-73CDBE0C672C'

SAML attribute settings

$config['saml_email_attribute']

description: . attribute used as From: email address of the authenticated user

default: mail

$config['saml_name_attribute']

description: attribute used to get the friendly name of the authenticated user. If this attribute does not exist or has no value (?) then FileSender will use the first part of the email attribute before the @ as the 'name_attribute' value.

default: cn

$config['saml_uid_attribute']

description: attribute to uniquely identify the user.

default: eduPersonTargetedID

Acceptable Use Policy (AUP) settings

$config["AuP_default"]

description: when set to false (the default) the user has to explicitly tick the 'I accept the AuP' checkbox before uploading a file. When set to true the checkbox will already be ticked.

default: false

$config["AuP"]

description: a text box with a AuP is displayed

default: true

$config["AuP_label"]

description: text label to show at the AuP checkbox

default: "I accept the terms and conditions of this service"

remark: the text is limited to the width of the AuP-box (will be 50 to 70 characters)

$config["AuP_terms"]

description: text to show in the AuP box containing the terms and conditions the user has to accept before using the service.

default: "AuP Terms and conditions"

remark: line breaks can be specified with \n or 'as is' (just continu the text on the next line), beware of the use of quotes.

example: "Terms and conditions\n\nTerm 1\n\nCondition2\n\nClosing remark."

Server settings

$config['default_daysvalid']

description: Maximum number of days before a file or a voucher is expired

default: 20

$config['ban_extension']

description: Possibly dangerous file extensions that are disallowed

default: = 'exe,bat'

$config["max_email_recipients"]

description: maximum email addresses allowed to send at once for voucher or file sending, a value of 0 allows unlimited emails.

default: 100

$config['max_flash_upload_size']

description: the maximum files size when uploading with Flash (no Gears installed (version 1.0 or no HTML5 support (version 1.1)), specify in number of bytes.

default: '2147483648' (2 GigaByte)

remarks: the value specified will be compared with the PHP settings post_max_size and upload_max_filesize. The minimum of these values will be used as actual maximum upload size for Flash uploads.

$config['max_gears_upload_size']

description: the maximum file size when uploading with Gears (version 1.0) or HTML5 (version 1.1), specify in number of bytes.

default: '107374182400' (100 GigaByte)

$config["server_drivespace_warning"]

description: the percentage of free space on the storage device at (or below) which a warning message is mailed to the administrator(s) as specified in $config['adminEmail'].

default: 20 (= send a warning when 20% or less space is left)

Advanced server settings

This section contains settings that under normal circumstances don't need changing. Do not change them unless you have a very good reason.

$config['postgresdateformat']

description: Date/Time format for PostgreSQL, use PHP date format specifier syntax

default: 'Y-m-d H:i:sP'

$config["crlf"]

description: controls whether lines in emails sent out by FileSender are terminated with CRLF or with LF. What makes sense depends on your PHP and email setup. Linux/Unix hosts will need "\n". Possible values are "\n" or "\r\n". Keep this at the default unless you have some weird setup.

default: '\n'

$config['voucherRegEx']

description: When someone uses a voucher, the voucher is in the format of 8 numbers/letters followed by - 4numlet-4numlet-4-12numlet unique Id that's standard flash and windows GUID (generated unique id). The regex is to make sure that a presented voucherId adheres to this GUID format. Anything else will result in a 'bugger off'. Also makes sure that generated vouchers are constructed correctly. Reason for putting it in config is because the PhP uniqueId is a different format so you'd need a different RegEx. So this is future proofing the vouchers.

default: '[a-zA-Z0-9]{8}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{12}'

$config['voucherUIDLength']

description: See above. Make sure no-one tries anything 'interesting' with vouchers.

default:'36'

$config['emailRegEx']

description: Regular expression to check the syntax of email-adressess

default: '[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?'

Site URL settings

These settings define the basic URL's FileSender will use. The configuration file will in general automatically define them based on the server name of the webserver which is automatically set in the global PHP variable $_SERVER['SERVER_NAME'] The following piece of code in config.php handles the automatic configuration:

if ( isset($_SERVER['SERVER_NAME']) ) {
$prot =  isset($_SERVER['HTTPS']) ? 'https://' : 'http://';
$config['site_url'] = $prot . $_SERVER['SERVER_NAME'] . '/filesender/'; // URL to Filesender
$config['site_simplesamlurl'] =  $prot . $_SERVER['SERVER_NAME'] . '/simplesaml/';
$config['site_authenticationSource'] ="default-sp";
$config['site_logouturl'] = $config['site_url'] . 'logout.php';
$config['site_downloadurl'] = $config['site_url'] . 'files/'; // * Deprecated *
}

Settings within this block can be modified as long as you keep those settings within the block.

$prot

description: variable containing the automatically determined current protocol (http or https) of the connection

default: isset($_SERVER['HTTPS']) ? 'https://' : 'http://'

remark: do not change

$config['site_url']

description: URL on your webserver where the FileSender instance can be reached

default: $prot . $_SERVER['SERVER_NAME'] . '/filesender/'

remarks: URL is automatically generated based on the SERVER_NAME and a manually specified local path ('/filesender/' by default). If you have your FileSender running on another URL you can change the local path part. At a minimum, this part should contain '/' which means FileSender is running at the root of your webserver.

example: $prot . $_SERVER['SERVER_NAME'] . '/'

$config['site_simplesamlurl']

description: URL on your webserver where the SimpleSAMLphp instance can be reached

default: $prot . $_SERVER['SERVER_NAME'] . '/simplesaml/'

remark: URL is automatically generated based on the SERVER_NAME and a manually specified local path ('/simplesaml/' by default). If you have your SimpleSAMLphp instance running on another URL you can change the local path part. If you have your FileSender instance reachable with http (no forced SSL) but want to force authentication via simplesaml to use SSL change the $prot part to 'https://' (including quotes).

example: 'https://' . $_SERVER['SERVER_NAME'] . '/simplesamlphp/

$config['site_authenticationSource']

description: authentication source on your SimpleSAMLphp instance to use

default: "default-sp"

example: "example-userpass" ; Point FileSender to the 'example-userpass' authentication source defined in the SimpleSAMLphp authsources.php

$config['site_logouturl']

description: URL to go to when the user logs out (will be used by the IdP to redirect to)

remark: should be an absolute URL including protocol and host, by default this will be the URL part as generated in $config['site_url'] plus a local path part (default 'logout.php')

default: $config['site_url'] . 'logout.php'

example: $config['site_url'] . 'custom-logout.php'

$config['site_downloadurl']

description: in beta release before 0.1.16 this was used for download URLs. Deperecated as of beta 0.1.16

status: deprecated, do not use, do not remove.

default: $config['site_url'] . 'files/'

The following setting is outside the if {} block but is related to the server URL settings:

$config['forceSSL']

description: when set to true (default, recommended) FileSender will force connections to always use SSL

values: true/false

default: true

Support links

These settings can be used to point the user to custom help/about/gears pages. URLs specified here are opened in a new browser window/tab and can be relative (pointing to a file/script in the www directory of your FileSender instance) or absolute (including external sites).

$config['aboutURL']

description: URL to go to when the 'About' link in the UI is selected.

default: "about.php"

example: "local-about.php"

example: "http://support.example.org/about-filesender.aspx"

$config['helpURL']

description: URL to go to when the 'Help' link in the UI is selected.

default: "help.php"

example: "local-help.php"

example: "http://support.example.org/help-for-filesender.aspx"

$config['gearsURL']

description: URL to go to when the 'Gears' (1.0) or 'HTML5' (1.1) link in the UI is selected.

default: 'http://tools.google.com/gears/' // Version 1.0(.x)

default: 'http://html5test.com/' // Version 1.1

example: 'local-gears-information.php'

File and directory location settings

These settings define the directory locations where various files can be found or stored. Directory values are absolute filesystem paths on your server and should be readable and writable (except for the site_simplesamllocation) for the webserver user.

$config['site_filestore']

description: the directory where all uploaded files are stored

remarks: this directory should have ample disk space and can fysically be stored on a NAS or other big storage device.

default: '/usr/share/filesender/files/'

example: '/data/filesender/files/'

$config['site_temp_filestore']

description: the directory used to store (partial) Gears uploads. After completion of the Gears upload the temporary file will be moved to the 'site_filestore'

remarks: this directory is not used for Flash uploads. You might want to do a regular check on this directory to remove old partial but never finished uploads. It is advised to keep this directory on the same partition as the actual 'site_filestore' so moving the temporary file will be instantaneous.

default: = '/usr/share/filesender/tmp/'

$config['site_simplesamllocation']

description: directory where the SimpleSAMLphp software can be found. Needed to find the required SImpleSAMLphp libraries.

default: = '/usr/share/simplesamlphp/'

$config['log_location']

description: directory to keep FileSender specific logfiles.

remarks: logfiles are created per day (and per user/voucheruid for client_specific_logging). FileSender has no internal mechanism to clean up old logs, you might want to do a (automated) regular cleanup of this directory.

default: '/usr/share/filesender/log/'

Database related settings

$config['pg_host']

description: the hostname of the host where the FileSender database server resides. Simplest setup is on the FileSender server

default: 'localhost'

$config['pg_database']

description: Name of the Postgresql database that will be used to store FileSender's meta data. Files are stored directly on disk.

default: 'filesender'

$config['pg_port']

description: TCP port of the Postgresql database that FileSender will connect to

default: '5432'

$config['pg_username']

description: username used to authenticate to the Postgresql database

default:none

example: 'filesender'

$config['pg_password']

description: password to authenticate to the Postgresql database

default: none

example: 'databasepassword'

Cron settings

$config['cron_exclude prefix']

description: exclude deletion of files with the prefix character listed (can use multiple characters eg '._' will ignore .xxxx and _xxxx
default: '_'

Email related configuration directives

FileSender sends out 5 types of email to users. In the configuration file you can define templates for these emails. These templates can contain template variables that will be filled when the actual email is created. This section details the configuration file directives for those email templates and the email template variables.

** finished except for the mapping of which variables can be used with which templates **

$config['default_emailsubject']

description: if a FileSender user refrains from entering an email subject then this subject will be used

usable template variables: {siteName}, {filename}

default value: "{siteName}: {filename}";

$config['filedownloadedemailbody']

description: email sent to the sender of a file when a recipient has downloaded that file.

usable template variables:

$config['fileuploadedemailbody']

description: email sent to the recipient(s) of an uploaded file that the file is available for download.

usable template variables:

$config['voucherissuedemailbody']

description:email sent to a recipient of a voucher that a voucher is available to upload a file.

usable template variables:

$config['defaultvouchercancelled']

description: email sent to a recipient of a voucher that said voucher is now cancelled.

usable template variables:

$config['defaultfilecancelled']

description: email sent to a recipient of a file that said file is now cancelled.

usable template variables:

Email template variables

In email templates you can use certain variables that will be expanded by FileSender when the emails are actually created. The following template variables can be used in the email subject and the email body:

{fileto}

will be replaced with the recipient address of the mail

usable in emails: fileuploadedemailbody, filedownloadedemailbody

{filefrom}

will be replaced with the sender address of the mail

usable in emails: fileuploadedemailbody, filedownloadedemailbody

{siteName}

will be replaced with the site name as specified in $config['site_name']

usable in emails: filedownloadedemailbody, fileuploadedemailbody, voucherissuedemailbody, defaultvouchercancelled, defaultfilecancelled

{filename} {fileoriginalname}

will be replaced with the original filename.

usable in emails: fileuploadedemailbody, filedownloadedemailbody

{htmlfilename}

usable in the HTML part of emails: fileuploadedemailbody, filedownloadedemailbody

Same as {filename} but with html encoding of unsafe characters. Always use this variable to specify the filename in HTML parts of a mail

{serverURL}

will be replaced with URL as defined in $config['site_url']

usable in emails:

{filevoucheruid}

will be replaced with the voucher ID of the file or voucher (?)

usable in emails:

{fileexpirydate}

will be replaced with the expiry date of the file

usable in emails:

{filesize}

will be replaced with the filesize of the file

usable in emails:

{CRLF}

used to insert a line break in emails.

{charset}

will be replaced with the charset detected in the actual message

used in the MIME headers of emails:fileuploadedemailbody, filedownloadedemailbody

Not implemented/unused

The settings in this section are in the 1.0 config.php file but are not implemented, unfinished, deprecated or otherwise not used in version 1.0 of FileSender. You should not use, change or remove these settings.

$config['site_sendfileinstructions'] = 'To send a file. Type an email address into the To: box Select BROWSE to choose a file on your compu ter. Select SEND FILE to upload and send the file.';

$config['site_voucherinstructions'] = 'A Voucher allows someone to send you a file. To create a voucher. Enter an email address then select Send Vouc her. An email will be sent to the recipient with a link to use the Voucher.';

$config['site_downloadinstructions'] = 'A file is available for you. Select Download File to download the file to your computer.';

$config['available_space'] = '20000M';

description: put in here to flag somehow that only so much space was allowed to be used. Should be replaced by something that says 'give a trigger to the admin when the available space is down to so many% of the total'. Not in use at the moment.
default: $config['available_space'] = '20000M';

$config['about'] = true;

description: triggers the display of a link to an about page in the Flash UI. The about page itself can be found in www/about.php
default: $config['about'] = true;

$config["help_link_visible"] = true;

$config['site_defaultlanguage'] = 'EN_AU';

$config['site_icon'] = 'cloudstor.png';

$config['site_css'] = '';