Sign Up Free Log In
Why OFS? Features Pricing Docs FAQ

User Guide (3.1 and older)

Regular Usage

This section covers the regular usage of your ObjectiveFS file system, including:

  • Creating a new file system
  • Mounting an existing file system
  • Unmounting an existing file system
  • Destroying a file system

ObjectiveFS uses environment variables to set up and manage your file system. It supports reading environment variables from files in a directory. Environment variables can also be set on the command line or set in your shell (e.g. .bashrc file). For more details or setup info, see the environment variables section.

Create

To create a new file system, follow the steps below. The file system is automatically mounted after file system creation.

  1. Pick a globally unique, non-secret, file system name e.g. myfs.
  2. Pick a strong passphrase, write it down and store it somewhere safe.
    IMPORTANT: Without the passphrase, there is no way to recover any files.
  3. Run the following command, and your new file system is now ready.

A. Environment Variables from Directory (Recommended)
Synopsis:
sudo ./mount.objectivefs -n -o env=<env dir> <filesystem name>

Example:

$ sudo ./mount.objectivefs -n -o env=/etc/objectivefs.env myfs
Welcome to ObjectiveFS.
Passphrase (for myfs): [enter passphrase]
Verify passphrase (for myfs): [enter passphrase again]
Directory to mount [/objectivefs]: [enter dir]
INFO: new filesystem created

B. Environment Variables on Command Line
Synopsis:
sudo [<ENV VAR>='<value>'] ./mount.objectivefs -n <filesystem name>

Example:

$ sudo AWS_ACCESS_KEY_ID='your s3 access key' \
  AWS_SECRET_ACCESS_KEY='your secret s3 key' \
  OBJECTIVEFS_LICENSE='your objectivefs license key' \
  ./mount.objectivefs -n myfs
Welcome to ObjectiveFS.
Passphrase (for myfs): [enter passphrase]
Verify passphrase (for myfs): [enter passphrase again]
Directory to mount [/objectivefs]: [enter dir]
INFO: new filesystem created

Mount

Your file system can be mounted on your Linux and OS X machines. After the file system is mounted, you can use it for reading and writing just like a local disk. Everything under your selected directory (/objectivefs above) is stored encrypted in Amazon S3 or Google Cloud Storage.

If your machine sleeps while having the file system mounted, the file system will remain mounted and working after it wakes up, even if your network has changed. A common scenario is a laptop that is used in multiple locations (e.g. office, home, airport).

On each server that you want to share your file system, run the following command.

A. Environment Variables from Directory (Recommended)
Synopsis:
sudo ./mount.objectivefs -o env=<env dir> <filesystem name>

Example:

$ sudo ./mount.objectivefs -o env=/etc/objectivefs.env myfs
Welcome to ObjectiveFS.
Passphrase (for myfs): [enter passphrase]
Directory to mount [/objectivefs]: [enter dir]
INFO: objectivefs ready

B. Environment Variables on Command Line
Synopsis:
sudo [<ENV VAR>='<value>'] ./mount.objectivefs <filesystem name>

Example:

$ sudo AWS_ACCESS_KEY_ID='your s3 access key' \
  AWS_SECRET_ACCESS_KEY='your secret s3 key' \
  OBJECTIVEFS_LICENSE='your objectivefs license key' \
  ./mount.objectivefs myfs
Welcome to ObjectiveFS.
Passphrase (for myfs): [enter passphrase]
Directory to mount [/objectivefs]: [enter dir]
INFO: objectivefs ready

Mount on Boot

If you would like your directory mounted automatically on your Linux servers upon startup, follow the steps below.

  1. Install mount.objectivefs as /sbin/mount.objectivefs
  2. Create a directory (e.g. /etc/objectivefs.env) with your environment variables.
    (See the environment variables section for details).

  3. Add a line with the following fields to /etc/fstab:
    <fs name>  <mount dir>  objectivefs  env=<env dir>,_netdev[,<opts>]  0 0

    _netdev is used by many Linux distributions to mark the filesystem as a network filesystem. Example line to add to /etc/fstab: 

    myfs /objectivefs  objectivefs  env=/etc/objectivefs.env,_netdev  0 0

  4. Make sure that network file systems are enabled on boot. For example, you can use chkconfig to turn on netfs.

`$ chkconfig --level 3 netfs on
$ chkconfig --list netfs
netfs           0:off   1:off   2:off   3:on    4:on    5:on    6:off`

Unmount

To unmount a file system, just run the following command. Your data is stored securely in the cloud even when unmounted, and will be available when you mount your file system again.

Synopsis:
sudo umount <mount directory>

Example:

$ sudo umount /objectivefs

Destroy

IMPORTANT: After a destroy, there is no way to recover any files or data.

To destroy a filesystem and delete it from the object store (S3 or GCS), run the following command and use your current Authorization Key to confirm.

A. Environment Variables from Directory (Recommended)
Synopsis:
sudo ./mount.objectivefs -d -o env=<env dir> <filesystem name>

Example:

$ sudo ./mount.objectivefs -d -o env=/etc/objectivefs.env myfs

B. Environment Variables on Command Line
Synopsis:
sudo [<ENV VAR>='<value>'] ./mount.objectivefs -d <filesystem name>

Example:

$ sudo AWS_ACCESS_KEY_ID='your s3 access key' \
  AWS_SECRET_ACCESS_KEY='your secret s3 key' \
  OBJECTIVEFS_LICENSE='your objectivefs license key' \
  ./mount.objectivefs -d myfs

Advanced Usage

This section covers options you can run ObjectiveFS with, and provides description of the different supported environment variables.

Mount Options

ObjectiveFS is run from the command line and accepts the following options.

Synopsis:
mount.objectivefs [-o <option> [,<option>]] [<fs name> [<mount dir>]]

Description:

<fs name>
Your globally unique, non-secret file system name. The program will prompt if it is not provided.
<mount dir>
Directory on your machine to mount your file system on. The program will prompt if it is not provided.
-o env=<dir>
Load environment variables from directory <dir>. See environment variable section.
-o strictatime | relatime | noatime
Update / Smart update / Don’t update access time. (Default: Smart update)
-o diratime | nodiratime
Update / Don’t update directory access time. (Default: Update)
-o suid | nosuid
Allow / Disallow suid bits. (Default: Allow)
-o dev | nodev
Allow block and character devices. (Default: Allow)
-o exec | noexec
Allow binary execution. (Default: Allow)
-o ro | rw
Read-only / Read-write file system. (Default: Read-write)
-o compact | nocompact
Enable / disable background index compaction. (Default: Enable)
-o region=<region options>

Select region for new bucket. (Default: us-west-2)
Region options:

  • us-west-1
  • us-west-2
  • eu-west-1
  • ap-southeast-1
  • ap-southeast-2
  • ap-northeast-1
  • sa-east-1

All options can also be found by running:

$ ./mount.objectivefs -h

Environment Variables

ObjectiveFS uses environment variables for configuration. You can set them using any standard method. We also support reading environment variables from a directory.

A. Environment Variables from Directory
ObjectiveFS supports reading environment variables from files in a directory, similar to the envdir tool from the daemontools package.

Your environment variables are stored in a directory. Each file in the directory corresponds to an environment variable, where the file name is the environment variable name and the first line of the file content is the value.

Synopsis:
sudo ./mount.objectivefs -o env=<env dir> <args>

Setup

Step 1. Create a directory to store the environment variables, e.g. /etc/objectivefs.env/.
Step 2. Set each filename to an environment variable, and set the file content to the value.
See also setup example at: one-time setup

Example: The content of each file is the value of the environment variable.

$ ls /etc/objectivefs.env/
AWS_ACCESS_KEY_ID  AWS_SECRET_ACCESS_KEY  OBJECTIVEFS_LICENSE  OBJECTIVEFS_PASSPHRASE

B. Environment Variables on Command Line
ObjectiveFS also supports user-provided environment variables through the command line. The user-provided environment variables will take precedence over the parameters specified in the environment directory.

Synopsis:
sudo [<ENV VAR>='<value>'] ./mount.objectivefs <args>

SUPPORTED ENVIRONMENT VARIABLES

ACCOUNT
Username of the user to run as. Root will be dropped after startup.
AWS_ACCESS_KEY_ID
Your S3 access key.
AWS_DEFAULT_REGION
Your prefered S3 region. (default: us-west-2)
AWS_METADATA_HOST
AWS STS host publishing session keys (for EC2 set to “169.254.169.254”). Sets and rekeys AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SECURITY_TOKEN. (added in 2.1)
AWS_SECRET_ACCESS_KEY
Your secret S3 key.
AWS_SECURITY_TOKEN
Session security token when using AWS STS.
CACHESIZE
Set cache size as a percentage of memory (e.g. 30%) or absolute value (e.g. 500M or 1G). (default: 20% of memory, minimum: 64MB)
DNSCACHEIP
IP address of recursive name resolver (default to /etc/resolv.conf).
OBJECTIVEFS_LICENSE
Your ObjectiveFS license key.
OBJECTIVEFS_PASSPHRASE
Passphase for filesystem. (default: will prompt)

AWS EC2 IAM Roles

If you have attached an IAM role to your EC2 instance, you can set AWS_METADATA_HOST to 169.254.169.254 to automatically rekey.

Files

/etc/resolv.conf
Recursive name resolvers from this file are used unless the DNSCACHEIP environment variable is set.

Logging

Log information is printed to the terminal when running in the foreground, and is sent to syslog when running in the background.

ObjectiveFS only runs in the background when the filesystem name and mount directory are both given on the command line. To override, use the -f foreground flag.

Errors

403 Permission denied
Your S3 keys do not have permissions to access S3. Check that your user keys are added to a group with all S3 permissions.
./mount.objectivefs: Permission denied
mount.objectivefs needs executable permissions set. Run chmod +x mount.objectivefs

Tips

Backups

As with all filesystems, please keep backups of everything important.

Passphrase

Pick a strong passphrase (e.g. five or six random dictionary words), write it down and store it somewhere safe.
IMPORTANT: Without the passphrase, there is no way to recover any files.

Questions

Don’t hesitate to give us a call at +1-415-997-9967, or send us an email at support@objectivefs.com.