# DOcument eXchange (DOX)

### Overview

DOX offers web based document exchange with versioning, syncing and user management.
DOX is designed as a modern replacement of ftp with rsync features.
DOX must be enabled by the fexmaster, it is a configuration option and not activated per default.

DOX consists of folders (toplevel directories) with their specific configuration (users, access, etc), stored on the F*EX server.
A folder can contain any number of document files or subdirectories.
As with F*EX archive sharing DOX documents do not have an expiration date. They stay online, until you delete them.

DOX is not suitable for backup purposes, because it does not convey file attributes like permissions, ownerships or ACLs and it cannot handle hard links correctly.
Better use archive sharing for this task.

### Usage

You can use DOX with any webbrowser with javascript support.

With the CLI client fexdox from the fextools package you can synchronize a local directory with DOX, either for upload or for download.

### Owner and users

DOX has two different views: owner or user

- For owner view you must be logged in as owner, using your regular F*EX login.
  It offers you an overview of all your folders and backup versions.
  Entering a folder or backup version shows its content.
  An owner can create any number of folders and upload files or directories in a folder.
  Example screenshots (click for full size):

  Files and directories with a "#" prefix are private: they are blocked for user access, only the owner can read them.

- For user view you need a DOX URL from the owner, e.g. https://fex.rus.uni-stuttgart.de/dox/framstag@rus.uni-stuttgart.de/test/
  It offers you read access only to this folder (and subdirectories).
  A user can read or download files or directories.
  A user cannot see or read blocked files or directories.
  For upload he needs a special user account, see below.
  Example screenshot (click for full size):

Both, owner and user, can use the CLI client fexdox for file syncing and a webbrowser to download or upload documents.

Some document types like GIF PNG JPG PDF HTML TXT can be viewed directly with a webbrowser.

### Folders and configuration

You can create a folder either with your webbrowser, or with the CLI client fexdox
A folder on the fexserver has the same name as your local directory.
Allowed characters for the folder name are A-Z a-z 0-9 @ ~ ^ . , + -
All other characters will be substituted with "_" (underscore).

A `/FOLDER/.fexdox/` configuration subdirectory will be automatically created.

`/FOLDER/.fexdox/config` contains the configuration:

`backups=NUMBER` | # how many backup versions fexdox automatically creates and keeps (default: 1)
`useraccess=no` | # no access for other users
`useraccess=yes` | # access for other users listed in the users file (default)
`useraccess=anonymous` | # anonymous read access for everybody
`charset=NAME` | # character set name for files (default: utf-8)
`showdelete=all` | # show [delete] button for folders and backups (default)
`showdelete=backup` | # show [delete] button for backups
`showdelete=no` | # show no [delete] button

In `/FOLDER/.fexdox/users` you can write your users with passwords:

      USER1:PASSWORD1
      USER2:PASSWORD2
      USER3:PASSWORD3
      ...

User and password can be any string (without spaces and colons).
If the user string is an email address, this user can send files to the owner via [send file] button.

You can further restrict user access to specific ips or ip ranges via configuration file `/FOLDER/.fexdox/access` with the content:

      IP1
      IP2-IP3
      ...

User access to specific files and directories can be blocked via `/FOLDER/.fexdox/private` with the content:

      FILE1
      FILE2
      DIR1/FILE3
      ...

You can use the well known shell meta characters (wild cards) "*" "?" "[...]" in the file and directory names.
Files and directories with names beginning with "." or "#" or ending with "~" are implicitly blocked.
No user will see or can download blocked files.

### User upload

To allow user upload the owner has to create an upload directory for him.
This can be done in `/FOLDER/.upload` via

[Create] an upload directory for user ...

Below you can set a "!publish" flag.
Only users with this flag are able to move their uploads to the regular folder.
Without this flag you (the owner) have to do this manually.
Otherwise the uploaded files stay in the upload directory, invisable for other users.

### Extras

In `.#.html` or `#.html` you can put HTML code which will be displayed above the directory listing, e.g:

    <h1>This directory contains great stuff about hotchpotch</h1>

### Versioning

The owner can create or delete a backup version of a folder via webbrowser.
A backup version is represented as DATE_TIME string.
Backup versions are not accessible by users.
The owner can restore single files or directories or the whole backup version.
The client fexdox automatically creates a new backup and keeps only that number of backups specified in `/FOLDER/.fexdox/config`, older backups will be deleted!

### Folder actions

[backup] | create backup version
[restore] | restore backup version
[delete] | delete backup version
[DELETE] | delete the folder with all backups

### Directory actions

[list it] | list all files in all directories on one page
[zip it] | make a zip archive and offer a download link
[fex it] | fex the files to your email address
[sync it] | start fexsync for download
[stream it] | start sexsend for download (prefered download methode for BIG folders)
[reload] | reload the page

### File actions

[zip it] | make a zip archive of the the selected files and offer download link
[fex it] | fex the selected files to your email address
[copy] | copy the selected files to another folder
[move] | move the selected files to another directory
[rename] | rename the selected files (you will be prompted for new names)
[publish] | move the selected files from the upload area to the regular folder directory
[delete] | delete the selected files

### Other actions

[mirror] | mirror (download to server directory) an URL

### Restrictions

- a folder name must consist of characters [A-Za-z0-9@_.+-]
- DOX cannot handle files or directories with newline character in their names
- directory web upload is (only) possible with Google Chrome, but no file attributes will be conveyed besides the modification date
- hard links will be broken between partial updates
- transfers of more than 4 GB with a webbrowser are volatile, better use client fexdox

### Comparison with archive sharing

#include "comparison.html"

Names in UPPERCASE in this document are placeholders, you have to substitute them with real values!