Object Storage Based Filesystem with s3fs

Introduction

This tutorial explains how to mount an S3 bucket onto the local filesystem of a server using s3fs.

Recommendation: This guide uses Hetzner Object Storage, which offers S3-compatible storage with excellent price-performance ratio and European data centers. More information: Hetzner Object Storage Documentation

Step 1 - Installation

• For Ubuntu/Debian:

  sudo apt-get update
  sudo apt-get install s3fs

• For CentOS/RHEL:

  sudo yum install s3fs-fuse

• From source (if needed):

  sudo apt-get install automake autotools-dev g++ git libcurl4-gnutls-dev libfuse-dev libssl-dev libxml2-dev make pkg-config
  git clone https://github.com/s3fs-fuse/s3fs-fuse.git
  cd s3fs-fuse
  ./autogen.sh
  ./configure
  make
  sudo make install

Step 2 - Configure Access Credentials and mount point

For Hetzner Object Storage, create access credentials in the Hetzner Cloud Console

1. Create a credentials file:

   echo "ACCESS_KEY_ID:SECRET_ACCESS_KEY" | sudo tee /root/.passwd-s3fs > /dev/null

2. Set proper permissions:

   sudo chmod 600 /root/.passwd-s3fs

3. Create the mount point

   sudo mkdir /mnt/s3storage

Step 3 - Mounting Options

In the mount commands, replace <bucket_name> and https://nbg1.your-objectstorage.com/ with your actual bucket name and endpoint.

If you use Hetzner Object Storage, the URL must be chosen according to the region where your Bucket was created. You can find your region in the Hetzner Cloud Console under "Object Storage". You can find a list of available regions and endpoints in their Object Storage overview. Example: If your Bucket was created in Nuremberg, use the URL https://nbg1.your-objectstorage.com in your mount commands and fstab. You cannot change the region after the Bucket was created.

Note: An incorrect endpoint URL will result in connection errors.

• Manual Mount Command

  sudo s3fs <bucket_name> /mnt/s3storage \
       -o url=https://nbg1.your-objectstorage.com/ \
       -o allow_other \
       -o use_path_request_style \
       -o use_cache=/tmp/s3fs \
       -o multipart_size=100 \
       -o parallel_count=8 \
       -o big_writes \
       -o kernel_cache \
       -o umask=0022 \
       -o enable_noobj_cache \
       -o retries=5 \
       -o ensure_diskfree=20000 \
       -o connect_timeout=180 \
       -o max_dirty_data=1024 \
       -o max_stat_cache_size=100000 \
       -o passwd_file=/root/.passwd-s3fs

• Automatic Mount via fstab

  Add this line to /etc/fstab:

  s3fs#<bucket_name> /mnt/s3storage fuse _netdev,allow_other,use_path_request_style,url=https://nbg1.your-objectstorage.com/,use_cache=/tmp/s3fs,multipart_size=100,parallel_count=8,big_writes,kernel_cache,umask=0022,enable_noobj_cache,retries=5,ensure_diskfree=20000,connect_timeout=180,max_dirty_data=1024,max_stat_cache_size=100000,passwd_file=/root/.passwd-s3fs 0 0

Configuration Parameters Explained:

Network Settings

Cache Configuration

Performance Options

Permission Settings

Step 4 - Testing and Verification

• Test Mount Command

  # Manual mount
  sudo s3fs your-bucket /mnt/s3storage [options as above]
  
  # Verify mount
  df -h
  mount | grep s3fs

• Test fstab Entry

  # Test fstab entry without reboot
  sudo mount -a
  
  # Verify mount
  df -h
  mount | grep s3fs

Step 5 - Troubleshooting

• Debug Mode

  # Add these options for debugging
  -o dbglevel=info -f -o curldbg

• Common Issues

  Permission Problems:

  # Check file permissions
  sudo ls -la /root/.passwd-s3fs
  ls -la /mnt/s3storage

  Cache Issues:

  # Clear cache
  sudo rm -rf /tmp/s3fs/*

Step 6 - Maintenance

• Unmounting

  # Manual unmount
  sudo umount /mnt/s3storage
  
  # Force unmount if needed
  sudo umount -f /mnt/s3storage

• Cache Management

  # Clear cache
  sudo rm -rf /tmp/s3fs/*
  
  # Create new cache directory
  sudo mkdir -p /tmp/s3fs
  sudo chmod 777 /tmp/s3fs

Step 7 - Security Best Practices

1. Always use HTTPS endpoints
2. Secure credentials file:

   sudo chmod 600 /root/.passwd-s3fs

3. Regular permission audits
4. Monitor access logs
5. Implement backup strategy

Step 8 - Performance Optimization for Object Storage

For optimal performance with object storage:

• Choose the closest endpoint to your server
• Use appropriate multipart_size (100MB is good for most cases)
• Adjust parallel_count based on your bandwidth (8-16 is recommended)
• Enable kernel_cache for better read performance
• Use big_writes for improved write performance
• Consider using a server that is in the same region as your object storage

Remember to test thoroughly after any configuration changes.

Conclusion

In /mnt/s3storage, you should see the contents of you S3 bucket. Via this path, you can now add or remove data in your bucket just as you would in any other directory on the server.

License: MIT