For release 5.0 and newer, please refer to the this guide.
It’s quick and easy to get started with your ObjectiveFS file system. Just 3 steps to get your new file system up and running. (see Get Started)
ObjectiveFS runs on your Linux and OSX machines, and implements a log-structured file system with a cloud object store backend, such as AWS S3, Google Cloud Storage (GCS) or your on-premise object store. Your data is encrypted before leaving your machine, and stays encrypted until it returns to your machine.
This user guide covers the commands and options supported by ObjectiveFS. For an overview of the commands, refer to the Command Overview section. For detailed description and usage of each command, refer to the Reference section.
What you need
sudo mount.objectivefs config [<directory>]sudo mount.objectivefs create [-l <region>] <filesystem>sudo mount.objectivefs list [-a] [<filesystem>]Run in background:
sudo mount.objectivefs [-o <opt>[,<opt>]..] <filesystem> <dir>
Run in foreground:
sudo mount.objectivefs mount [-o <opt>[,<opt>]..] <filesystem> <dir>
sudo umount <dir>sudo mount.objectivefs destroy <filesystem>This section covers the detailed description and usage for each ObjectiveFS command.
SUMMARY: Sets up the required variables to run objectiveFS
USAGE:
sudo mount.objectivefs config [<directory>]DESCRIPTION:
Config is a one-time operation that sets up the required credentials, such as object store keys and your license, as environment variables in a directory.
<directory>/etc/objectivefs.envWHAT YOU NEED:
AWS_ACCESS_KEY_ID)AWS_SECRET_ACCESS_KEY)EXAMPLES:
A. Default setup: your credentials will be created at /etc/objectivefs.env
$ sudo mount.objectivefs config
Creating config in /etc/objectivefs.env
Enter ObjectiveFS license: <your ObjectiveFS license>
Enter Access Key Id: <your AWS or GCS access key>
Enter Secret Access Key: <your AWS or GCS secret key>
B. User-specified destination directory
$ sudo mount.objectivefs config /home/tom/.ofs.env
Creating config in /home/tom/.ofs.env
Enter ObjectiveFS license: <your ObjectiveFS license>
Enter Access Key Id: <your AWS or GCS access key>
Enter Secret Access Key: <your AWS or GCS secret key>
TIPS:
/etc/objectivefs.env/AWS_ACCESS_KEY_ID)AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and OBJECTIVEFS_LICENSE in the environment directory. See environment variables section for details.SUMMARY: Creates a new file system
USAGE:
sudo mount.objectivefs create [-l <region>] <filesystem>DESCRIPTION:
This command creates a new file system in your S3 or GCS object store. You need to provide a passphrase for the new file system. Please choose a strong passphrase, write it down and store it somewhere safe.
IMPORTANT: Without the passphrase, there is no way to recover any files.
<filesystem>s3://myfs or myfs.gs://myfs or myfs. -l <region>ObjectiveFS also supports creating multiple file systems per bucket. Please refer to the filesystem pool section for details.
WHAT YOU NEED:
EXAMPLES:
A. Create an S3 file system in the default region (us-west-2)
# Assumption: your /etc/objectivefs.env has S3 keys
$ sudo mount.objectivefs create myfs
Passphrase (for s3://myfs): <your passphrase>
Verify passphrase (for s3://myfs): <your passphrase>
B. Create an S3 file system in a user-specified region (e.g. eu-central-1)
# Assumption: your /etc/objectivefs.env has S3 keys
$ sudo mount.objectivefs create -l eu-central-1 s3://myfs
Passphrase (for s3://myfs): <your passphrase>
Verify passphrase (for s3://myfs): <your passphrase>
C. Create a GCS file system in the default region
# Assumption: your /etc/objectivefs.env has GCS keys
$ sudo mount.objectivefs create gs://myfs
Passphrase (for gs://myfs): <your passphrase>
Verify passphrase (for gs://myfs): <your passphrase>
D. Create a GCS file system in a user-specified region (e.g. US)
# Assumption: your /etc/objectivefs.env has GCS keys
$ sudo mount.objectivefs create -l US myfs
Passphrase (for gs://myfs): <your passphrase>
Verify passphrase (for gs://myfs): <your passphrase>
TIPS:
OBJECTIVEFS_PASSPHRASE (e.g. /etc/objectivefs.env/OBJECTIVEFS_PASSPHRASE). This lets you run mount without needing to manually enter your passphrase every time.OBJECTIVEFS_LICENSE)./home/tom/.ofs.env: $ sudo OBJECTIVEFS_ENV=/home/tom/.ofs.env mount.objectivefs create myfsSUMMARY: Lists your file systems in S3 or GCS
USAGE:
sudo mount.objectivefs list [-a] [<filesystem>]DESCRIPTION:
This command lists file systems in your object store backend: S3 or GCS, depending on your keys in /etc/objectivefs.env. The output includes the file system name, kind (i.e. ofs for regular file system or pool (see filesystem pool)), and region (see region list)
-a<filesystem>myfs or s3://myfs or gs://myfs.WHAT YOU NEED:
EXAMPLES:
A. Default case with S3 keys: all of your ObjectiveFS file systems are listed
$ sudo mount.objectivefs list
NAME KIND REGION
s3://myfs-1 ofs us-west-2
s3://myfs-2 ofs eu-central-1
s3://myfs-3 ofs ap-southeast-1
s3://myfs-pool/ pool us-west-2
s3://myfs-pool/myfs-a ofs us-west-2
s3://myfs-pool/myfs-b ofs us-west-2
s3://myfs-pool/myfs-c ofs us-west-2
B. Default case with GCS keys: all of your ObjectiveFS file systems are listed
$ sudo mount.objectivefs list
NAME KIND REGION
gs://myfs-1 ofs US
gs://myfs-2 ofs EU
gs://myfs-3 ofs ASIA
gs://myfs-pool/ pool US
gs://myfs-pool/myfs-a ofs US
gs://myfs-pool/myfs-b ofs US
gs://myfs-pool/myfs-c ofs US
C. List a specific file system, e.g. s3://myfs-2
$ sudo mount.objectivefs list s3://myfs-2
NAME KIND REGION
s3://myfs-2 ofs eu-central-1
D. List everything, including non-ObjectiveFS buckets. In the example below, s3://my-bucket is a non-ObjectiveFS bucket.
$ sudo mount.objectivefs list -a
NAME KIND REGION
s3://myfs-1 ofs us-west-2
s3://myfs-2 ofs eu-central-1
s3://myfs-3 ofs ap-southeast-1
s3://my-bucket - us-west-1
TIPS:
/home/tom/.ofs.env: $ sudo OBJECTIVEFS_ENV=/home/tom/.ofs.env mount.objectivefs listSUMMARY: Mounts your file system on your Linux or OSX machines.
USAGE:
Run in background:
sudo mount.objectivefs [-o <opt>[,<opt>]..] <filesystem> <dir>Run in foreground:
sudo mount.objectivefs mount [-o <opt>[,<opt>]..] <filesystem> <dir>DESCRIPTION:
This command mounts your file system on a directory on your Linux or OSX machine. After the file system is mounted, you can read and write to it just like a local disk.
If your machine sleeps while the file system is mounted, the file system will remain mounted and working after it wakes up, even if your network has changed. This is useful for a laptop that is used in multiple locations.
You can mount the same file system on as many Linux or OSX machines as you’d like to share your file system with.
NOTE: The mount command requires sudo. It runs in the foreground if “mount” is provided, and runs in the background otherwise.
<filesystem><dir>General Mount Options
-o env=<dir>Mount Point Options
-o dev | nodev-o diratime | nodiratime-o exec | noexec-o nonempty-o ro | rw-o strictatime | relatime | noatime-o suid | nosuidFile System Mount Options
-o compact | nocompact-o hpc | nohpc-o mt | nomt | cputhreads=<N> | iothreads=<N>-o ratelimit | noratelimitWHAT YOU NEED:
EXAMPLES:
Assumptions:
1. /ofs is an existing empty directory
2. Your passphrase is in /etc/objectivefs.env/OBJECTIVEFS_PASSPHRASE
A. Mount an S3 file system
$ sudo mount.objectivefs mount myfs /ofsB. Mount a GCS file system with a different env directory, e.g. /home/tom/.ofs_gs.env
$ sudo mount.objectivefs mount -o env=/home/tom/.ofs_gs.env gs://myfs /ofs
C. Mount an S3 file system in the background
$ sudo mount.objectivefs s3://myfs /ofs
D. Mount a GCS file system with non-default options
Assumption: /etc/objectivefs.env contains GCS keys.
$ sudo mount.objectivefs mount -o nosuid,nodev,noexec,noatime gs://myfs /ofs
TIPS:
OBJECTIVEFS_PASSPHRASE in the environment directory (e.g. /etc/objectivefs.env/OBJECTIVEFS_PASSPHRASE). This lets you run the mount command without needing to manually enter your passphrase every time.
Please verify that its permission is the same as other files in the environment directory (e.g. OBJECTIVEFS_LICENSE)./home/tom/.ofs.env: $ sudo OBJECTIVEFS_ENV=/home/tom/.ofs.env mount.objectivefs mount myfs /ofsObjectiveFS supports Mount on Boot, where your directory is mounted automatically upon reboot.
WHAT YOU NEED:
A. Linux
Check that /etc/objectivefs.env/OBJECTIVEFS_PASSPHRASE exists so you can mount your filesystem without needing to enter the passphrase.
If it doesn’t exist, create the file with your passphrase as the content.(see details)
Add a line to /etc/fstab with:
<filesystem> <mount dir> objectivefs auto,_netdev[,<opts>] 0 0 _netdev is used by many Linux distributions to mark the file system as a network file system.
B. OSX
OSX can use launchd to mount on boot. See Mount on Boot Setup Guide for OSX for details.
SUMMARY: Unmounts your files system on your Linux or OSX machines
USAGE:
sudo umount <dir>DESCRIPTION:
To unmount your filesystem, run umount with the mount directory.
Typing Control-C in the window where ObjectiveFS is running in the foreground will stop the filesystem, but may not unmount it. Please run umount to properly unmount the filesystem.
WHAT YOU NEED:
EXAMPLE:
$ sudo umount /ofsIMPORTANT: After a destroy, there is no way to recover any files or data.
SUMMARY: Destroys your file system. This is an irreversible operation.
USAGE:
sudo mount.objectivefs destroy <filesystem>DESCRIPTION:
This command deletes your file system from your S3 or GCS object store. Please make sure that you really don’t need your data anymore because this operation cannot be undone.
You will be prompted for the authorization code available on your user profile page. This code changes periodically. Please refresh your user profile page to get the latest code.
<filesystem>NOTE:
Your file system should be unmounted from all of your machines before running destroy.
WHAT YOU NEED:
EXAMPLE:
$ sudo mount.objectivefs destroy s3://myfs
*** WARNING ***
The filesystem 's3://mytest1' will be destroyed. All data (550 MB) will be lost permanently!
Continue [y/n]? y
Authorization code: <your authorization code>
This section covers the options you can run ObjectiveFS with.
This is a list of supported S3 and GCS regions. ObjectiveFS supports all regions for S3 and GCS.
AWS S3
GCS
RELATED COMMANDS:
REFERENCE:
AWS S3 regions, GCS regions
The table below lists the corresponding endpoints for each supported regions.
AWS S3
| Region | Endpoint |
|---|---|
| us-east-1 | s3-external-1.amazonaws.com |
| us-west-2 | s3-us-west-2.amazonaws.com |
| us-west-1 | s3-us-west-1.amazonaws.com |
| eu-west-1 | s3-eu-west-1.amazonaws.com |
| eu-central-1 | s3.eu-central-1.amazonaws.com or s3-eu-central-1.amazonaws.com |
| ap-southeast-1 | s3-ap-southeast-1.amazonaws.com |
| ap-southeast-2 | s3-ap-southeast-2.amazonaws.com |
| ap-northeast-1 | s3-ap-northeast-1.amazonaws.com |
| ap-northeast-2 | s3.ap-northeast-2.amazonaws.com or s3-ap-northeast-2.amazonaws.com |
| sa-east-1 | s3-sa-east-1.amazonaws.com |
| us-gov-west-1 | s3-us-gov-west-1.amazonaws.com |
GCS
All GCS regions have the endpoint storage.googleapis.com
ObjectiveFS uses environment variables for configuration. You can set them using any standard method (e.g. on the command line, in your shell). We also support reading environment variables from a directory.
The filesystem settings specified by the environment variables are set at start up. To update the settings (e.g. change the memory cache size, enable disk cache), please unmount your filesystem and remount it with the new settings (exception: live rekey).
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.
SETUP:
The Config command sets up your environment directory with 3 main environment variables:
AWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEYOBJECTIVEFS_LICENSEYou can also add additional environment variables in the same directory using the same format: where the file name is the environment variable and the first line of the file content is the value.
EXAMPLE:
$ ls /etc/objectivefs.env/
AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY OBJECTIVEFS_LICENSE OBJECTIVEFS_PASSPHRASE
$ cat /etc/objectivefs.env/OBJECTIVEFS_PASSPHRASE
your_objectivefs_passphrase
B. Environment Variables on Command Line
You can also set the environment variables on the command line. The user-provided environment variables will override the environment directory’s variables.
USAGE:
sudo [<ENV VAR>='<value>'] mount.objectivefs EXAMPLE:
$ sudo CACHESIZE=30% mount.objectivefs myfs /ofsSUPPORTED ENVIRONMENT VARIABLES
To enable a feature, set the corresponding environment variable.
-l <region> will override this variable, if present.AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SECURITY_TOKEN. (added in 2.1)30%) or absolute value (e.g. 500M or 1G). (Default: 20%) (see Memory Cache section)DESCRIPTION:
ObjectiveFS uses memory to cache data and metadata locally to improve performance and to reduce the number of S3 operations.
USAGE:
Use the CACHESIZE environment variable to set the memory cache size (see environment variables section for how to set environment variables).
You can set CACHESIZE to either the actual memory size (e.g. 500M or 2G) or as a percentage of memory (e.g. 30%). A minimum of 64MB will be used.
DEFAULT VALUE:
If CACHESIZE is not specified, the default is 20% of memory for machines with 3GB+ memory or 5%-20% (with a minimum of 64MB) for machines with less than 3GB memory.
EXAMPLES:
A. Set memory cache size to 30%
$ sudo CACHESIZE=30% mount.objectivefs myfs /ofsB. Set memory cache size to 2GB
$ sudo CACHESIZE=2G mount.objectivefs myfs /ofsRELEVANT INFO:
DESCRIPTION:
ObjectiveFS can use local disks to cache data and metadata locally to improve performance and to reduce the number of S3 operations. Once the disk cache is enabled, ObjectiveFS handles the operations automatically, with no additional maintenance required from the user.
The disk cache is compressed, encrypted and has strong integrity checks. It is robust and can be copied between machines and even manually deleted, when in active use. So, you can rsync the disk cache between machines to warm the cache or to update the content.
Since the disk cache’s content persists when your file system is unmounted, you get the benefit of fast restart and fast access when you remount your file system.
ObjectiveFS will always keep some free space on the disk, by periodically checking the free disk space. If your other applications use more disk space, ObjectiveFS will adjust and use less by shrinking its cache.
Multiple file systems on the same machine can share the same disk cache without crosstalk, and they will collaborate to keep the most used data in the disk cache.
RECOMMENDATION:
We recommend enabling disk cache when local SSD or harddrive is available.
(See how to mount an instance store on EC2 for disk cache).
USAGE:
The disk cache uses DISKCACHE_SIZE and DISKCACHE_PATH environment variables (see environment variables section for how to set environment variables). To enable disk cache, set DISKCACHE_SIZE.
DISKCACHE_SIZE:
<DISK CACHE SIZE>[:<FREE SPACE>].<DISK CACHE SIZE> to the actual space you want ObjectiveFS to use (e.g. 20G or 1T). If the value specified is larger than the actual disk (e.g. 1P), ObjectiveFS will try to use as much space as possible on the disk while preserving the free space.<FREE SPACE> to the amount of free space you want to keep on the volume (e.g. 5G). The default value is 3G (if free space is not specified) and the minimum is 0G.<FREE SPACE> is set to 0G, ObjectiveFS will try to use as much space as possible (useful for dedicated disk cache partition).DISKCACHE_PATH
DEFAULT VALUE:
Disk cache is disabled when DISKCACHE_SIZE is not specified.
EXAMPLES:
A. Set disk cache size to 20GB and use default free space (3GB)
$ sudo DISKCACHE_SIZE=20G mount.objectivefs myfs /ofsB. Use as much space as possible for disk cache and keep 10GB free space
$ sudo DISKCACHE_SIZE=1P:10G mount.objectivefs myfs /ofsC. Set disk cache size to 20GB and free space to 10GB and specify the disk cache path
$ sudo DISKCACHE_SIZE=20G:10G DISKCACHE_PATH=/var/cache/mydiskcache mount.objectivefs myfs /ofsD. Use the entire space for disk cache (when using dedicated volume for disk cache)
$ sudo DISKCACHE_SIZE=1P:0G mount.objectivefs myfs /ofsWHAT YOU NEED:
/var/cache/objectivefs or on your DISKCACHE_PATHRELEVANT INFO:
DISKCACHE_PATH.DISKCACHE_SIZE values, and are pointing to the same DISKCACHE_PATH, ObjectiveFS will use the minimum disk cache size and the maximum free space value.SIGHUP to the mount.objectivefs program, it will start the disk cache clean-up cycle.ObjectiveFS supports live rekeying which lets you update your AWS keys while keeping your filesystem mounted. With live rekeying, you don’t need to unmount and remount your filesystem to change your AWS keys. ObjectiveFS supports both automatic and manual live rekeying.
If you have attached an AWS EC2 IAM role to your EC2 instance, you can set AWS_METADATA_HOST to 169.254.169.254 to automatically rekey. With this setting, you don’t need to use the AWS_SECRET_ACCESS_KEY and AWS_ACCESS_KEY_ID environment variables.
You can also manually rekey by updating the AWS_SECRET_ACCESS_KEY and AWS_ACCESS_KEY_ID environment variables (and also AWS_SECURITY_TOKEN if used) and sending SIGHUP to mount.objectivefs. The running objectivefs program (i.e. mount.objectivefs) will automatically reload and pick up the updated keys.
ObjectiveFS is a log-structured filesystem that uses an object store for storage. Compaction combines multiple small objects into a larger object and brings related data close together. It improves performance and reduces the number of object store operations needed for each filesystem access. Compaction is a background process and adjusts dynamically depending on your workload and your filesystem’s characteristics.
USAGE:
You can specify the compaction rate by setting the mount option when mounting your filesystem.
Faster compaction increases bandwidth usage.
For more about mount options, see this section.
nocompact - disable compactioncompact - enable regular compactioncompact,compact - enable faster compaction (uses more bandwidth)compact,compact,compact - enable fastest compaction (uses most bandwidth)DEFAULT:
Compaction is enabled by default. If the filesystem is mounted on an EC2 machine in the same region as your S3 bucket, compact,compact is the default. Otherwise, compact is the default.
EXAMPLES:
A. To enable faster compaction
$ sudo mount.objectivefs -o compact,compact myfs /ofsB. To disable compaction
$ sudo mount.objectivefs -o nocompact myfs /ofsTIPS:
IUsed column of df -i.Business and Enterprise Plan Feature
Filesystem pool lets you have multiple file systems per bucket. Since AWS S3 has a limit of 100 buckets per account, you can use pools if you need lots of file systems.
A filesystem pool is a collection of regular filesystems to simplify the management of lots of filesystems. You can also use pools to organize your company’s file systems by teams or departments.
A file system in a pool is a regular file system. It has the same capabilities as a regular file system.
A pool is a top-level structure. This means that a pool can only contain file systems, and not other pools. Since a pool is not a filesystem, but a collection of filesystems, it cannot be mounted directly.
Reference: Managing Per-User Filesystems Using Filesystem Pool and IAM Policy
An example organization structure is:
|
|- myfs1 // one file system per bucket
|- myfs2 // one file system per bucket
|- mypool1 -+- /myfs1 // multiple file systems per bucket
| |- /myfs2 // multiple file systems per bucket
| |- /myfs3 // multiple file systems per bucket
|
|- mypool2 -+- /myfs1 // multiple file systems per bucket
| |- /myfs2 // multiple file systems per bucket
| |- /myfs3 // multiple file systems per bucket
:
To create a file system in a pool, use the regular create command with
<pool name>/<file system> as the filesystem argument.
sudo mount.objectivefs create [-l <region>] <pool>/<filesystem>NOTE:
-l <region> specification.EXAMPLE:
A. Create an S3 file system in the default region (us-west-2)
# Assumption: your /etc/objectivefs.env contains S3 keys
$ sudo mount.objectivefs create s3://mypool/myfsB. Create a GCS file system in the default region
# Assumption: your /etc/objectivefs.env contains GCS keys
$ sudo mount.objectivefs create -l EU gs://mypool/myfsWhen you list your file system, you can distinguish a pool in the KIND column. A file system inside of a pool is listed with the pool prefix.
You can also list the file systems in a pool by specifying the pool name.
sudo mount.objectivefs list [<pool name>]EXAMPLE:
A. In this example, there are two pools myfs-pool and myfs-poolb. The file systems in each pools are listed with the pool prefix.
$ sudo mount.objectivefs list
NAME KIND REGION
s3://myfs-1 ofs us-west-2
s3://myfs-2 ofs eu-central-1
s3://myfs-pool/ pool us-west-2
s3://myfs-pool/myfs-a ofs us-west-2
s3://myfs-pool/myfs-b ofs us-west-2
s3://myfs-pool/myfs-c ofs us-west-2
s3://myfs-poolb/ pool us-west-1
s3://myfs-poolb/foo ofs us-west-1
B. List all file systems under a pool, e.g. myfs-pool
$ sudo mount.objectivefs list myfs-pool
NAME KIND REGION
s3://myfs-pool/ pool us-west-2
s3://myfs-pool/myfs-a ofs us-west-2
s3://myfs-pool/myfs-b ofs us-west-2
s3://myfs-pool/myfs-c ofs us-west-2
To mount a file system in a pool, use the regular mount command with
<pool name>/<file system> as the filesystem argument.
Run in background:
sudo mount.objectivefs [-o <opt>[,<opt>]..] <pool>/<filesystem> <dir>Run in foreground:
sudo mount.objectivefs mount [-o <opt>[,<opt>]..] <pool>/<filesystem> <dir>EXAMPLES:
A. Mount an S3 file system and run the process in background
$ sudo mount.objectivefs s3://myfs-pool/myfs-a /ofsB. Mount a GCS file system with a different env directory, e.g. /home/tom/.ofs_gs.env and run the process in foreground
$ sudo mount.objectivefs mount -o env=/home/tom/.ofs_gcs.env gs://mypool/myfs /ofs
Same as the regular unmount command
To destroy a file system in a pool, use the regular destroy command with
<pool name>/<file system> as the filesystem argument.
sudo mount.objectivefs destroy <pool>/<filesystem>NOTE:
EXAMPLE:
Destroying an S3 file system in a pool
$ sudo mount.objectivefs destroy s3://myfs-pool/myfs-a
*** WARNING ***
The filesystem 's3://myfs-pool/myfs-a' will be destroyed. All data (550 MB) will be lost permanently!
Continue [y/n]? y
Authorization code: <your authorization code>
Business and Enterprise Plan Feature (Linux only)
DESCRIPTION:
Multithreading is a performance feature that can lower latency and improve throughput for your workload.
ObjectiveFS will spawn dedicated CPU and IO threads to handle operations such as data decompression, data integrity check, disk cache accesses and updates.
USAGE:
Multithreading mode can be enabled using the mt mount option, which sets the dedicated CPU threads to 4 and dedicated IO threads to 8. You can also explicitly specify the number of dedicated CPU threads and IO threads using the cputhreads and iothreads mount options. You can also use the -nomt mount option to disable multithreading.
| Mount options | Description |
|---|---|
| -o mt | sets cputhreads to 4 and iothreads to 8 |
| -o cputhreads=<N> | sets the number of dedicated CPU threads to N (min:0, max:128) |
| -o iothreads=<N> | sets the number of dedicated IO threads to N (min:0, max:128) |
| -o nomt | sets cputhreads and iothreads to 0 |
DEFAULT VALUE:
By default, there are 2 dedicated IO threads and no dedicated CPU threads.
EXAMPLE:
A. Enable default multithreading option (4 cputhreads, 8 iothreads)
$ sudo mount.objectivefs -o mt <filesystem> <dir> B. Set CPU threads to 8 and IO threads to 16
$ sudo mount.objectivefs -o cputhreads=8,iothreads=16 <filesystem> <dir> C. Example fstab entry to enable multithreading
s3://<filesystem> <dir> objectivefs auto,_netdev,mt 0 0Business and Enterprise Plan Feature
DESCRIPTION:
You can run ObjectiveFS with an http proxy to connect to your object store. A common use case is to connect ObjectiveFS to the object store via a squid caching proxy.
USAGE:
Set the http_proxy environment variable to the proxy server’s address (see environment variables section for how to set environment variables).
DEFAULT VALUE:
If the http_proxy environment is not set, this feature is disabled by default.
EXAMPLE:
Mount a filesystem (e.g. s3://myfs) with an http proxy running locally on port 3128:
$ sudo http_proxy=http://localhost:3128 mount.objectivefs mount myfs /ofsAlternatively, you can set the http_proxy in your /etc/objectivefs.env directory
$ ls /etc/objectivefs.env
AWS_ACCESS_KEY_ID OBJECTIVEFS_PASSPHRASE
AWS_SECRET_ACCESS_KEY http_proxy
OBJECTIVEFS_LICENSE
$ cat /etc/objectivefs.env/http_proxy
http://localhost:3128Enterprise Plan Feature
DESCRIPTION:
While our regular license check is very robust and can handle multi-day outages, some companies prefer to minimize external dependencies. For these cases, we offer a local license check feature that lets you run your infrastructure independent of any license server.
USAGE:
Please talk with your enterprise support contact for instructions on how to enable the local license check on your account.
Business and Enterprise Plan Feature
DESCRIPTION:
The admin mode provides an easy way to manage many filesystems in a programmatic way. You can use the admin mode to easily script the creation of many filesystems.
The admin mode lets admins create filesystems without the interactive passphrase confirmations. To destroy a filesystem, admins only need to provide a ‘y’ confirmation and don’t need an authorization code. Admins can list the filesystems, similar to a regular user. However, admins are not permitted to mount a filesystem, to separate the admin functionality and user functionality.
| Operation | User Mode | Admin Mode |
|---|---|---|
| Create | Needs passphrase confirmation | No passphrase confirmation needed |
| List | Allowed | Allowed |
| Mount | Allowed | Not allowed |
| Destroy | Needs authorization code and confirmation | Only confirmation needed |
USAGE:
Business and enterprise account users have an admin license key, in addition to their regular license key. Please contact support@objectivefs.com for this key.
To use admin mode, we recommend creating an admin-specific objectivefs environment directory, e.g. /etc/objectivefs.admin.env. Please use your admin license key for OBJECTIVEFS_LICENSE.
$ ls /etc/objectivefs.env/
AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY
OBJECTIVEFS_LICENSE OBJECTIVEFS_PASSPHRASE
$ cat /etc/objectivefs.env/OBJECTIVEFS_LICENSE
your_admin_license_key
You can have a separate user objectivefs environment directory, e.g. /etc/objectivefs.<user>.env, for each user to mount their individual filesystems.
EXAMPLES:
A. Create a filesystem in admin mode with credentials in /etc/objectivefs.admin.env
$ sudo OBJECTIVEFS_ENV=/etc/objectivefs.admin.env mount.objectivefs create myfsB. Mount the filesystem as user tom in the background
$ sudo OBJECTIVEFS_ENV=/etc/objectivefs.tom.env mount.objectivefs myfs /ofsBusiness and Enterprise Plan Feature
DESCRIPTION:
This feature lets you map local user ids and group ids to different ids in the remote filesystem.
The id mappings should be 1-to-1, i.e. a single local id should only be mapped to a single remote id, and vice versa. If multiple ids are mapped to the same id, the behavior is undetermined.
When a uid is remapped and U* is not specified, all other unspecified uids will be mapped to the default uid: 65534 (aka nobody/nfsnobody).
Similarly, all unspecified gids will be mapped to the default gid (65534) if a gid is remapped and G* is not specified.
USAGE:
IDMAP="<Mapping>[:<Mapping>]"
where Mapping is:
U<local id or name> <remote id>
G<local id or name> <remote id>
U* <default id>
G* <default id>
Mapping Format
A. Single User Mapping: U<local id or name> <remote id>
Maps a local user id or local user name to a remote user id.
B. Single Group Mapping: G<local id or name> <remote id>
Maps a local group id or local group name to a remote group id.
C. Default User Mapping: U* <default id>
Maps all unspecified local and remote users ids to the default id. If this mapping is not specified, all unspecified user ids will be mapped to uid 65534 (aka nobody/nfsnobody).
D. Default Group Mapping: G* <default id>
Maps all unspecified local and remote group ids to the default id. If this mapping is not specified, all unspecified group ids will be mapped to gid 65534 (aka nobody/nfsnobody).
EXAMPLES:
A. UID mapping only
IDMAP="U600 350:Uec2-user 400:U* 800"ec2-user is mapped to remote uid 400, and vice versaB. GID mapping only
IDMAP="G800 225:Gstaff 400"staff is mapped to remote gid 400, and vice versanobody/nfsnobody)nobody/nfsnobody)C. UID and GID mapping
IDMAP="U600 350:G800 225"nobody/nfsnobody)nobody/nfsnobody)Enterprise Plan Feature
DESCRIPTION:
ObjectiveFS supports AWS Server-Side encryption using Amazon S3-Managed Keys (SSE-S3) and AWS KMS-Managed Keys (SSE-KMS).
USAGE:
Use the AWS_SERVER_SIDE_ENCRYPTION environment variable (see environment variables section for how to set environment variables).
The AWS_SERVER_SIDE_ENCRYPTION environment variable can be set to:
AES256 (for Amazon S3-Managed Keys (SSE-S3))aws:kms (for AWS KMS-Managed Keys (SSE-KMS) with default key)<your kms key> (for AWS KMS-Managed Keys (SSE-KMS) with the keys you create and manage)REQUIREMENT:
To run SSE-KMS, stunnel is required. See the following guide for setup instructions.
EXAMPLES:
A. Create a filesystem called myfs with Amazon S3-Managed Keys (SSE-S3)
$ sudo AWS_SERVER_SIDE_ENCRYPTION=AES256 mount.objectivefs create myfsB. Create a filesystem called myfs with Amazon S3-Managed Keys (SSE-KMS)
Note: make sure stunnel is running. See setup instructions.
$ sudo http_proxy=http://localhost:8086 AWS_SERVER_SIDE_ENCRYPTION=aws:kms mount.objectivefs create myfsC. Mount a filesystem called myfs with Amazon KMS-Managed Keys (SSE-KMS) using the default key
Note: make sure stunnel is running. See setup instructions.
$ sudo http_proxy=http://localhost:8086 AWS_SERVER_SIDE_ENCRYPTION=aws:kms mount.objectivefs myfs /ofsD. Mount a filesystem called myfs with Amazon KMS-Managed Keys (SSE-KMS) using a specific key
Note: make sure stunnel is running. See setup instructions.
$ sudo http_proxy=http://localhost:8086 AWS_SERVER_SIDE_ENCRYPTION=<your aws kms key> mount.objectivefs myfs /ofsLog information is printed to the terminal when running in the foreground, and is sent to syslog when running in the background. On OSX, the log is typically at /var/log/system.log. On Linux, the log is typically at /var/log/messages or /var/log/syslog.
Below is a list of common log messages. For error messages, please see troubleshooting section.
A. Initial mount message
SUMMARY: The message logged every time an ObjectiveFS filesystem is mounted.
FORMAT:
objectivefs starting [<fuse version>, <region>, <endpoint>, <cachesize>, <disk cache setting>]DESCRIPTION:
<fuse version><region><endpoint><cachesize><disk cache setting>EXAMPLE:
objectivefs starting [fuse version 7.22, region us-west-2, endpoint http://s3-us-west-2.amazonaws.com, cachesize 753MB, diskcache off]
B. Regular log message
SUMMARY: The message logged while your filesystem is active. It shows the cumulative number of S3 operations and bandwidth usage since the initial mount message.
FORMAT:
<put> <list> <get> <delete> <bandwidth in> <bandwidth out>DESCRIPTION:
<put> <list> <get> <delete><bandwidth in> <bandwidth out>EXAMPLE:
1403 PUT, 571 LIST, 76574 GET, 810 DELETE, 5.505 GB IN, 5.309 GB OUT
C. Caching Statistics
SUMMARY: Caching statistics is part of the regular log message starting in ObjectiveFS v.4.2. This data can be useful for tuning memory and disk cache sizes for your workload.
FORMAT:
CACHE [<cache hit> <metadata> <data> <os>], DISK[<hit>]DESCRIPTION:
<cache hit><metadata><data><OS>Disk [<hit>]EXAMPLE:
CACHE [74.9% HIT, 94.1% META, 68.1% DATA, 1.781 GB OS], DISK [99.0% HIT]
D. Error messages
SUMMARY: Error response from S3 or GCS
FORMAT:
retrying <operation> due to <endpoint> response: <S3/GCS response> [x-amz-request-id:<amz-id>, x-amz-id-2:<amz-id2>]DESCRIPTION:
<operation>PUT, GET, LIST, DELETE operations that encountered the error message<endpoint><S3/GCS response><amz-id><amz-id2>EXAMPLE:
retrying GET due to s3-us-west-2.amazonaws.com response: 500 Internal Server Error, InternalError, x-amz-request-id:E854A4F04A83C125, x-amz-id-2:Zad39pZ2mkPGyT/axl8gMX32nsVn
DNSCACHEIP environment variable is set.Initial Setup
chmod +x mount.objectivefsDuring Operation
/usr/sbin/ntpdate pool.ntp.org./usr/sbin/ntpdate pool.ntp.org.noratelimit mount option.Unmount
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.
Upgrading To A New Release
ObjectiveFS is forward and backward compatible. Upgrading or downgrading to a different release is straightforward. You can also do rolling upgrades for multiple servers. To upgrade: install the new version, unmount and then remount your filesystem. (reference: how to upgrade to a new ObjectiveFS version)
Don’t hesitate to give us a call at +1-415-997-9967, or send us an email at support@objectivefs.com.