S3FS(1) User Commands S3FS(1)

s3fs - سامانه فایل مبتنی بر FUSE با پشتیبانی Amazon S3

برای کاربر ریشه (root).
برای کاربر بدون امتیاز ویژه.

دستور s3fs یک سامانه فایل مبتنی بر FUSE است که به شما امکان می‌دهد یک باکت Amazon S3 را مانند یک سامانه فایل محلی متصل (mount) کنید. این ابزار فایل‌ها را به شکل بومی و شفاف در S3 ذخیره می‌کند (بدین معنا که می‌توانید از سایر برنامه‌ها نیز برای دسترسی به همان فایل‌ها استفاده کنید).

دستور s3fs از فایل استاندارد اعتبارنامه‌های AWS (https://docs.aws.amazon.com/cli/latest/userguide/cli-config-files.html) ذخیره‌شده در ${HOME}/.aws/credentials پشتیبانی می‌کند. علاوه بر این، s3fs از یک فایل passwd سفارشی نیز پشتیبانی می‌کند. در صورتی که به توکن نشست AWS (session token) نیاز باشد، تنها می‌توان از قالب فایل اعتبارنامه‌های AWS استفاده کرد. فایل گذرواژه s3fs دارای این قالب است (اگر تنها یک مجموعه اعتبارنامه دارید از این قالب استفاده کنید):

accessKeyId:secretAccessKey

اگر بیش از یک مجموعه اعتبارنامه دارید، این ساختار نیز پشتیبانی می‌شود:

bucketName:accessKeyId:secretAccessKey

فایل‌های گذرواژه می‌توانند در دو مکان ذخیره شوند:


/etc/passwd-s3fs [0640]
$HOME/.passwd-s3fs [0600]

دستور s3fs همچنین متغیرهای محیطی AWS_ACCESS_KEY_ID و AWS_SECRET_ACCESS_KEY را شناسایی می‌کند.

چاپ راهنما.
  --version
چاپ نسخه.
گزینه اجرای FUSE در پیش‌زمینه - اجرا نشدن به عنوان دیمن (daemon).
گزینه تک‌رشته‌ای FUSE (غیرفعال‌سازی عملکرد چندرشته‌ای).

تمام گزینه‌های s3fs باید در قالبی ارائه شوند که در آن "opt" به صورت زیر است:

<option_name>=<option_value>
اگر نام باکت (و مسیر) در خط فرمان مشخص نشده باشد، باید این گزینه پس از گزینه -o برای نام باکت تعیین شود.
لیست کنترل دسترسی پیش‌ساخته (canned acl) پیش‌فرض برای اعمال روی تمام اشیاء نوشته‌شده در s3، مانند "private" یا "public-read". برای فهرست کامل canned ACLها به https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl مراجعه کنید.
تعداد دفعات تلاش مجدد برای یک تراکنش ناموفق S3.
پوشه محلی برای فایل‌های موقت.
پوشه محلی مورد استفاده برای کش محلی فایل.
در صورت تنظیم use_cache، بررسی می‌کند که آیا دایرکتوری کش وجود دارد یا خیر. اگر این گزینه مشخص نشود، در زمان اجرا هنگامی که دایرکتوری کش وجود ندارد، ایجاد خواهد شد.
حذف کش محلی فایل هنگام شروع و خروج s3fs.
ذخیره شیء با کلاس ذخیره‌سازی مشخص‌شده. مقادیر ممکن: standard، standard_ia، onezone_ia، reduced_redundancy، intelligent_tiering، glacier، glacier_ir، و deep_archive.
استفاده از Reduced Redundancy Storage آمازون. این گزینه نمی‌تواند همراه با use_sse مشخص شود. (می‌توان use_rrs=1 را برای نسخه‌های قدیمی مشخص کرد) این گزینه با گزینه جدید storage_class جایگزین شده است.
مشخص کردن سه نوع رمزگذاری سمت سرور آمازون: SSE-S3، SSE-C یا SSE-KMS. نوع SSE-S3 از کلیدهای رمزگذاری مدیریت‌شده توسط Amazon S3 استفاده می‌کند، SSE-C از کلیدهای رمزگذاری ارائه‌شده توسط مشتری بهره می‌برد، و SSE-KMS از کلید اصلی مدیریت‌شده توسط شما در AWS KMS استفاده می‌کند. می‌توانید "use_sse" یا "use_sse=1" را برای فعال‌سازی نوع SSE-S3 مشخص کنید (use_sse=1 پارامتر نسخه‌های قدیمی است). در صورت تنظیم SSE-C، می‌توانید "use_sse=custom"، "use_sse=custom:<custom key file path>" یا "use_sse=<custom key file path>" را مشخص کنید (تنها مشخص کردن <custom key file path> پارامتر نسخه قدیمی است). می‌توانید از "c" به عنوان کوتاه‌نوشت "custom" استفاده کنید. فایل کلید سفارشی باید دارای مجوز 600 باشد. فایل می‌تواند شامل چند خط باشد که هر خط یک کلید SSE-C است. خط اول در فایل به عنوان کلیدهای رمزگذاری ارائه‌شده توسط مشتری برای بارگذاری و تغییر سرآیندها و غیره استفاده می‌شود. اگر کلیدهایی بعد از خط اول وجود داشته باشد، برای بارگیری اشیائی استفاده می‌شوند که با کلیدی غیر از کلید اول رمزگذاری شده‌اند. بنابراین، می‌توانید تمام کلیدهای SSE-C را در یک فایل نگه‌دارید که به منزله تاریخچه کلیدهای SSE-C است. اگر "custom" ("c") را بدون مسیر فایل مشخص کنید، باید کلید سفارشی را با گزینه load_sse_c یا متغیر محیطی AWSSSECKEYS تنظیم کنید. (متغیر محیطی AWSSSECKEYS چند کلید SSE-C را با جداکننده ":" در خود دارد). این گزینه برای تعیین نوع SSE به کار می‌رود. بنابراین اگر نمی‌خواهید شیء هنگام بارگذاری رمزگذاری شود، اما نیاز به رمزگشایی شیء رمزگذاری‌شده هنگام بارگیری دارید، می‌توانید به جای این گزینه از گزینه load_sse_c استفاده کنید. برای تنظیم SSE-KMS، مقدار "use_sse=kmsid" یا "use_sse=kmsid:<kms id>" را مشخص کنید. می‌توانید از "k" به عنوان کوتاه‌نوشت "kmsid" استفاده کنید. اگر نوع SSE-KMS را با <kms id> خود در AWS KMS مشخص می‌کنید، می‌توانید آن را پس از "kmsid:" (یا "k:") قرار دهید. اگر فقط "kmsid" ("k") را مشخص کنید، باید متغیر محیطی AWSSSEKMSID را تنظیم کنید که مقدار آن <kms id> است. باید توجه داشته باشید که نمی‌توانید از شناسه KMS متعلق به منطقه‌ای غیر از همان منطقه EC2 استفاده کنید. علاوه بر این، در صورت مشخص کردن SSE-KMS، نقاط پایانی (endpoints) شما باید از لایه سوکت‌های امن (SSL) یا امنیت لایه انتقال (TLS) استفاده کنند.
مشخص کردن مسیر فایل کلیدهای رمزگذاری ارائه‌شده توسط مشتری جهت رمزگشایی هنگام بارگیری. اگر از کلید رمزگذاری ارائه‌شده توسط مشتری در زمان بارگذاری استفاده می‌کنید، آن را با "use_sse=custom" مشخص کنید. این فایل خطوط متعددی دارد که هر خط نشان‌دهنده یک کلید سفارشی است. بنابراین می‌توانید تمام کلیدهای SSE-C را در فایل نگهداری کنید که تاریخچه کلیدهای SSE-C محسوب می‌شود. محتوای متغیر محیطی AWSSSECKEYS دقیقاً همانند محتویات این فایل است.
مشخص کردن مسیر فایل گذرواژه، که نسبت به گذرواژه موجود در $HOME/.passwd-s3fs و /etc/passwd-s3fs اولویت دارد.
این گزینه مسیر فایل پیکربندی مربوط به سرآیند HTTP اضافی بر اساس پسوند فایل (شیء) را مشخص می‌کند.
قالب فایل پیکربندی به صورت زیر است:
-----------
line = [file suffix or regex] HTTP-header [HTTP-values]
file suffix = file (object) suffix, if this field is empty, it means "reg:(.*)".(=all object).
regex = regular expression to match the file (object) path. this type starts with "reg:" prefix.
HTTP-header = additional HTTP header name
HTTP-values = additional HTTP header value
-----------
نمونه:
-----------
.gz Content-Encoding gzip
.Z Content-Encoding compress
reg:^/MYDIR/(.*)[.]t2$ Content-Encoding text2
-----------
یک فایل پیکربندی نمونه در دایرکتوری "test" قرار داده شده است. اگر این گزینه را برای تنظیم سرآیند HTTP با عنوان "Content-Encoding" مشخص می‌کنید، لطفاً RFC 2616 را مد نظر قرار دهید.
انتخاب یک نمایه (profile) از ${HOME}/.aws/credentials برای احراز هویت در S3. توجه داشته باشید که این قالب با قالب AWS CLI همخوانی دارد و با قالب passwd مربوط به s3fs تفاوت دارد.
اتصال ناشناس یک باکت عمومی هنگام تنظیم روی 1؛ فایل‌های $HOME/.passwd-s3fs و /etc/passwd-s3fs را نادیده می‌گیرد. سرویس S3 اجازه فراخوانی API رونوشت شیء (copy object) را به کاربران ناشناس نمی‌دهد، از این رو هنگام مشخص شدن گزینه public_bucket=1، s3fs به طور خودکار گزینه nocopyapi را فعال می‌کند.
مدت زمان انتظار برای برقراری اتصال پیش از صرف‌نظر کردن.
مدت زمان انتظار میان فعالیت خواندن/نوشتن پیش از صرف‌نظر کردن.
مشخص کردن حداکثر تعداد کلیدهای بازگردانده‌شده توسط S3 list object API. مقدار پیش‌فرض ۱۰۰۰ است. می‌توانید این مقدار را روی ۱۰۰۰ یا بیشتر تنظیم کنید.
حداکثر تعداد مدخل‌ها در کش stat و کش پیوند نمادین.
مشخص کردن زمان انقضا (ثانیه) برای مدخل‌ها در کش stat و کش پیوند نمادین. این زمان انقضا نشان‌دهنده زمان سپری‌شده از هنگام کش شدن است.
مشخص کردن زمان انقضا (ثانیه) برای مدخل‌ها در کش stat و کش پیوند نمادین. این زمان انقضا بر اساس زمان سپری‌شده از آخرین دسترسی به آن کش محاسبه می‌شود. این گزینه با stat_cache_expire مانعة‌الجمع است و برای سازگاری با نسخه‌های قدیمی‌تر حفظ شده است.
این گزینه وضعیت عدم وجود اشیاء را در کش stat نگه‌داری می‌کند. هنگامی که این کش منفی فعال باشد، درخواست‌های اضافی HeadObject را برای جستجوی اشیاء ناموجود پردازش نمی‌کند که این امر کارایی را بهبود می‌بخشد. این قابلیت به طور پیش‌فرض فعال است، بنابراین نیازی به تعیین آن نیست.
به طور پیش‌فرض، s3fs عدم وجود اشیاء را در کش stat ذخیره می‌کند. این گزینه کش‌گذاری منفی را غیرفعال می‌سازد. این کار از تاخیر در به‌روزرسانی‌ها به دلیل نگهداری کش جلوگیری می‌کند. با این حال، ممکن است تعداد درخواست‌های HeadObject را برای بررسی وجود یک شیء افزایش دهد که می‌تواند موجب کاهش عملکرد شود..TP -o no_check_certificate (این گزینه به‌طور پیش‌فرض غیرفعال است) گواهی سرور در برابر مرجع‌های صدور گواهی (CA) موجود بررسی نخواهد شد.
اگر 0 باشد، گواهی SSL در برابر نام میزبان (hostname) اعتبارسنجی نمی‌شود.
یک گواهی کلاینت SSL را مشخص می‌کند. این پارامتر اختیاری را در قالب زیر مشخص کنید:
"<SSL Cert>[:<Cert Type>[:<Private Key>[:<Key Type>
[:<Password>]]]]"
<SSL Cert>: گواهی کلاینت.
مسیر فایل یا NickName (برای NSS و غیره) را مشخص کنید.
<Cert Type>: نوع گواهی، پیش‌فرض "PEM" است (اختیاری).
<Private Key>: فایل کلید خصوصی گواهی (اختیاری).
<Key Type>: نوع کلید خصوصی، پیش‌فرض "PEM" است (اختیاری).
<Password>: عبارت عبور کلید خصوصی (اختیاری). همچنین می‌توان این مقدار را حذف کرد و آن را با استفاده از متغیر محیطی "S3FS_SSL_PRIVKEY_PASSWORD" مشخص نمود.
ابزار s3fs همواره از حافظهٔ پنهان DNS استفاده می‌کند؛ این گزینه حافظهٔ پنهان DNS را غیرفعال می‌سازد.
ابزار s3fs همواره از حافظهٔ پنهان نشست SSL استفاده می‌کند؛ این گزینه حافظهٔ پنهان نشست SSL را غیرفعال می‌سازد.
اندازهٔ بخش (part)، بر حسب مگابایت، برای هر درخواست چندبخشی (multipart). حداقل مقدار ۵ مگابایت و حداکثر مقدار ۵ گیگابایت است.
اندازهٔ بخش، بر حسب مگابایت، برای هر درخواست رونوشت چندبخشی، مورد استفاده برای تغییر نام‌ها و mixupload. حداقل مقدار ۵ مگابایت و حداکثر مقدار ۵ گیگابایت است. برای رونوشت گرفتن از اشیایی با حداکثر اندازهٔ ۵ ترابایت، باید حداقل ۵۱۲ مگابایت باشد، اما مقادیر کمتر ممکن است عملکرد را بهبود ببخشند.
تخلیه داده‌های تغییریافته (dirty data) به S3 پس از نوشتن تعداد معینی مگابایت. حداقل مقدار ۵۰ مگابایت است. مقدار -1 به معنای غیرفعال بودن است. همراه با nomixupload قابل استفاده نیست.
اندازهٔ باکت (bucket) که عناصر متناظر ساختار statvfs با آن پر خواهند شد. آرگومان این گزینه یک عدد صحیح است که اختیاری می‌تواند با یک پسوند ضریبی (GB، GiB، TB، TiB، PB، PiB، EB، EiB) همراه باشد (بدون فاصله بین آن‌ها). اگر پسوندی ارائه نشود، بایت در نظر گرفته می‌شود؛ مثلاً: 20000000، 30GB، 45TiB. توجه داشته باشید که s3fs اندازهٔ واقعی حجم را محاسبه نمی‌کند (بسیار سنگین و پرهزینه است): به‌طور پیش‌فرض حداکثر اندازهٔ ممکن را در نظر می‌گیرد؛ با این حال، از آنجا که این امر ممکن است نرم‌افزارهای دیگری را که از s3fs استفاده می‌کنند سردرگم کند، می‌توان اندازهٔ اعلام‌شدهٔ باکت را با این گزینه تنظیم نمود.
مقدار مگابایت را برای تضمین فضای خالی دیسک تعیین می‌کند. این گزینه آستانهٔ اندازهٔ فضای خالی روی دیسک را مشخص می‌کند که برای فایل حافظهٔ پنهان توسط s3fs استفاده می‌شود. ابزار s3fs فایل‌هایی را برای بارگیری، بارگذاری و حافظهٔ پنهان ایجاد می‌کند. اگر فضای خالی دیسک کمتر از این مقدار باشد، s3fs تا حد امکان از فضای دیسک استفاده نمی‌کند که این کار به بهای افت کارایی تمام می‌شود.
حداقل نسبت فضای خالی دیسک را تعیین می‌کند. مقدار این گزینه می‌تواند بین 0 تا 100 باشد. این گزینه اندازهٔ حافظهٔ پنهان را بر اساس این نسبت کنترل می‌کند تا اطمینان حاصل شود که نسبت خالی بودن دیسک از این مقدار بیشتر است. برای مثال، هنگامی که فضای دیسک 50GB باشد، مقدار پیش‌فرض اطمینان حاصل می‌کند که دیسک حداقل 50GB * 10%% = 5GB فضای باقی‌مانده رزرو خواهد کرد.
آستانه، بر حسب مگابایت، برای استفاده از بارگذاری چندبخشی به‌جای تک‌بخشی. باید حداقل ۵ مگابایت باشد.
حداکثر اندازه، بر حسب مگابایت، برای یک رونوشت تک‌بخشی پیش از تلاش برای رونوشت چندبخشی.
میزبانی غیر از آمازون را تنظیم می‌کند، مثلاً https://example.com.
یک مسیر سرویس تعیین می‌کند، زمانی که میزبان غیرآمازونی به یک پیشوند نیاز دارد.
آدرس url را برای دسترسی به Amazon S3 تعیین می‌کند. اگر می‌خواهید از HTTP استفاده کنید، می‌توانید "url=http://s3.amazonaws.com" را تنظیم نمایید. اگر از https استفاده نمی‌کنید، لطفاً URL را با گزینهٔ url مشخص نمایید.
منطقه (region) مورد استفاده در نسخهٔ ۴ امضا (signature version 4) را تعیین می‌کند. اگر این گزینه مشخص نشود، s3fs به‌طور پیش‌فرض از منطقهٔ "us-east-1" استفاده می‌کند. اگر s3fs نتواند به منطقهٔ مشخص‌شده با این گزینه متصل شود، قادر به اجرا نخواهد بود. اما اگر این گزینه را مشخص نکنید و اتصال با منطقهٔ پیش‌فرض ممکن نباشد، s3fs تلاش مجدد خواهد کرد تا به‌طور خودکار به منطقهٔ دیگر متصل شود. به این ترتیب s3fs می‌تواند نام صحیح منطقه را بفهمد، زیرا s3fs می‌تواند آن را از خطای دریافتی از سرور S3 استخراج کند. همچنین می‌توانید از گزینهٔ قدیمی -o endpoint استفاده کنید که مفهوم یکسانی دارد.
امضای درخواست‌های AWS را تنها با استفاده از نسخهٔ ۲ امضا تنظیم می‌کند.
امضای درخواست‌های AWS را تنها با استفاده از نسخهٔ ۴ امضا تنظیم می‌کند.
مقدار umask را برای دایرکتوری نقطهٔ اتصال (mount point) تعیین می‌کند. اگر گزینهٔ allow_other تنظیم نشده باشد، s3fs دسترسی به نقطهٔ اتصال را تنها برای مالک مجاز می‌داند. در حالت برعکس، s3fs به‌طور پیش‌فرض به تمام کاربران اجازهٔ دسترسی می‌دهد. اما اگر allow_other را همراه با این گزینه تنظیم کنید، می‌توانید مجوزهای نقطهٔ اتصال را همانند umask با این گزینه کنترل نمایید.
مقدار umask را برای فایل‌های زیر نقطهٔ اتصال تنظیم می‌کند. این کار می‌تواند به کاربرانی غیر از کاربر متصل‌کننده امکان خواندن و نوشتن در فایل‌هایی را بدهد که خودشان ایجاد نکرده‌اند.
بارگذاری جریانی (stream upload) را فعال می‌کند. اگر این گزینه فعال باشد، در طول بارگذاری چندبخشی، هم‌زمان با عملیات نوشتن، یک بارگذاری متوالی به‌صورت موازی از بخشی که نوشته شده است انجام خواهد شد. انتظار می‌رود این کار عملکرد بهتری نسبت به سایر توابع بارگذاری ارائه دهد. توجه داشته باشید که این گزینه هنوز آزمایشی است و ممکن است در آینده تغییر کند.
این مقدار حداکثر تعداد درخواست‌های موازی ارسالی و همچنین تعداد پردازش‌های موازی برای درخواست‌های head، بارگذاری‌های چندبخشی و بارگذاری‌های جریانی است. رشته‌های کارگر (worker threads) برای پردازش درخواست‌ها بر اساس این مقدار راه‌اندازی خواهند شد.
به سرور S3 اجازه می‌دهد یکپارچگی داده‌های بارگذاری‌شده را از طریق هدر Content-MD5 بررسی کند. این کار می‌تواند بار پردازشی اضافه (CPU overhead) بر انتقال‌ها تحمیل کند.
مقدار Content-SHA256 را برای محموله‌های (payloads) PutObject و UploadPart محاسبه نمی‌کند. این کار می‌تواند بار پردازشی اضافهٔ CPU را در انتقال‌ها کاهش دهد.
این گزینه به s3fs دستور می‌دهد تا به‌جای آدرس متادیتای نمونه (instance metadata)، آدرس متادیتای اعتبارسنجی کانتینر ECS را استعلام کند.
این گزینه به نام IAM role یا "auto" نیاز دارد. اگر "auto" را مشخص کنید، s3fs به‌طور خودکار از نام‌های IAM role تنظیم‌شده برای نمونه استفاده می‌کند. اگر این گزینه را بدون هیچ آرگومانی مشخص نمایید، همانند تعیین مقدار "auto" خواهد بود.
سرویس متادیتای نمونهٔ AWS، که با احراز هویت IAM role استفاده می‌شود، از توکن API پشتیبانی می‌کند. اگر از IAM role در محیطی استفاده می‌کنید که از IMDSv2 پشتیبانی نمی‌کند، فعال‌سازی این پرچم باعث صرف‌نظر کردن از دریافت و استفاده از توکن API در هنگام دریافت اعتبارهای IAM می‌شود.
این گزینه به s3fs دستور می‌دهد تا از احراز هویت IBM IAM استفاده کند. در این حالت، مقادیر AWSAccessKey و AWSSecretKey به‌ترتیب به‌عنوان Service-Instance-ID و APIKey آی‌بی‌ام استفاده خواهند شد.
نشانی URL مورد استفاده برای احراز هویت IBM IAM را تعیین می‌کند.
کتابخانهٔ مشترکی (shared library) را مشخص می‌کند که اطلاعات احراز هویت شامل توکن احراز هویت را پردازش می‌کند. اگر این گزینه مشخص شود، پردازش اطلاعات هویتی و توکن ارائه‌شده توسط کتابخانهٔ مشترک به‌جای پردازش توکار اعتبارنامه‌ها انجام خواهد شد. این گزینه را نمی‌توان همراه با گزینه‌های passwd_file، profile، use_session_token، ecs، ibm_iam_auth، ibm_iam_endpoint، imdsv1only و iam_role مشخص کرد.
گزینه‌هایی را برای ارسال به کتابخانهٔ مشترکِ مشخص‌شده در credlib هنگام بارگذاری و سپس مقداردهی اولیهٔ آن تعیین می‌کند. برای رشتهٔ مشخص‌شده در این گزینه، رشته‌ای را مشخص کنید که توسط کتابخانهٔ مشترک تعریف شده است.
مدیریت صفت‌های گسترش‌یافته (xattrs) را فعال می‌کند. اگر این گزینه را تنظیم کنید، می‌توانید از صفت‌های گسترش‌یافته استفاده نمایید. برای مثال، ابزارهای encfs و ecryptfs نیازمند پشتیبانی از صفت‌های گسترش‌یافته هستند. توجه: اگر s3fs صفت‌های گسترش‌یافته را مدیریت کند، دستور رونوشت همراه با preserve=mode روی آن کار نخواهد کرد.
ثبت فضای نام xml را برای پاسخ‌های ListBucketResult، ListVersionsResult و غیره غیرفعال می‌کند. فضای نام پیش‌فرض از "http://s3.amazonaws.com/doc/2006-03-01" جستجو می‌شود. در حال حاضر نباید از این گزینه استفاده کرد، زیرا s3fs پس از نسخهٔ v1.66 به‌طور خودکار xmlns را جستجو می‌کند.
استفاده از PUT (copy api) را هنگام بارگذاری چندبخشی اشیای با اندازهٔ بزرگ غیرفعال می‌کند. به‌طور پیش‌فرض هنگام انجام بارگذاری چندبخشی، برای بازهٔ داده‌های بدون تغییر تا جای ممکن از PUT (copy api) استفاده خواهد شد. هنگامی که nocopyapi یا norenameapi مشخص شده باشد، استفاده از PUT (copy api) حتی در صورت مشخص نبودن این گزینه نیز باطل می‌شود.
برای ذخیره‌سازهای شیء توزیع‌شده‌ای که سازگار با S3 API هستند اما از PUT (copy api) پشتیبانی نمی‌کنند. اگر این گزینه را تنظیم کنید، s3fs از PUT همراه با "x-amz-copy-source" (copy api) استفاده نخواهد کرد. از آنجا که این گزینه ترافیک شبکه را ۲ تا ۳ برابر افزایش می‌دهد، استفاده از آن توصیه نمی‌شود.
برای ذخیره‌سازهای شیء توزیع‌شده‌ای که سازگار با S3 API هستند اما از PUT (copy api) پشتیبانی نمی‌کنند. این گزینه زیرمجموعه‌ای از گزینهٔ nocopyapi است. گزینهٔ nocopyapi برای هیچ دستوری از copy-api استفاده نمی‌کند (مانند chmod، chown، touch، mv و غیره)، اما این گزینه فقط برای دستور تغییر نام (مانند mv) از copy-api استفاده نمی‌کند. اگر این گزینه همراه با nocopyapi مشخص شود، s3fs آن را نادیده می‌گیرد.
سازگاری با APIهای شبه S3 که از شیوهٔ درخواست virtual-host پشتیبانی نمی‌کنند را با استفاده از شیوهٔ قدیمی‌تر درخواست بر مبنای مسیر (path request style) فعال می‌کند..TP -o listobjectsv2 (استفاده از ListObjectsV2) ارسال ListObjectsV2 به‌جای ListObjects، که در مخازن اشیایی (object stores) فاقد پشتیبانی از ListObjects مفید است.
به‌طور معمول s3fs مقدار User-Agent را در قالب "s3fs/<version> (commit hash <hash>; <using ssl library name>)" خروجی می‌دهد. اگر این گزینه مشخص شود، s3fs از خروجی دادن User-Agent خودداری می‌کند.
سفارشی‌سازی فهرست مجموعه‌رمزهای TLS. نیازمند فهرستی از نام‌های مجموعه‌رمز است که با دونقطه (colon) از هم جدا شده‌اند. فهرستی از مجموعه‌رمزهای در دسترس بسته به موتور TLS شما، در مستندات کتابخانه CURL قابل مشاهده است: https://curl.haxx.se/docs/ssl-ciphers.html
نام نمونه (instance name) برای نقطه اتصال فعلی s3fs. این نام به پیام‌های ثبت گزارش و سرآیندهای User-Agent ارسال‌شده توسط s3fs اضافه خواهد شد.
در صورتی که یک شیء فایل یا دایرکتوری فاقد سرآیند x-amz-meta-mode باشد، s3fs کمبود اطلاعات درباره حالت فایل/دایرکتوری (mode) را جبران می‌کند. به‌طور پیش‌فرض، s3fs اطلاعات stat را برای یک شیء تکمیل نمی‌کند، که در نتیجه اجازه فهرست کردن یا ویرایش آن شیء داده نخواهد شد.
برنامه s3fs به‌طور پیش‌فرض از دو طرح نام‌گذاری متفاوت "dir/" و "dir" برای نگاشت نام دایرکتوری‌ها به اشیاء S3 و برعکس پشتیبانی می‌کند. به عنوان حالت سوم، در صورتی که یک شیء فایل دارای مسیر (مانند "/dir/file") اما بدون دایرکتوری والد باشد، دایرکتوری‌ها می‌توانند به‌طور غیرمستقیم مشخص شوند. این گزینه حالت چهارمی یعنی "dir_$folder$" را که توسط برنامه‌های قدیمی‌تر ایجاد می‌شد، فعال می‌کند.
برنامه s3fs تنها از طرح اول "dir/" برای ایجاد اشیاء S3 مربوط به دایرکتوری‌ها استفاده می‌کند.
پشتیبانی از این طرح‌های نام‌گذاری متفاوت، موجب افزایش بار ارتباطی می‌شود.
اگر مجوزهای دسترسی به باکت (bucket) را ندارید و مسیر دایرکتوری ایجادشده توسط کلاینتی غیر از s3fs را برای نقطه اتصال مشخص کنید، اجرا امکان‌پذیر نخواهد بود زیرا دایرکتوری نقطه اتصال توسط s3fs پیدا نمی‌شود. اما با مشخص کردن این گزینه، می‌توانید از این خطا جلوگیری کنید.
سرویس S3 نیازمند این است که تمامی نام‌های اشیاء به‌صورت UTF-8 معتبر باشند. اما برخی کلاینت‌ها، به‌ویژه کلاینت‌های NFS ویندوز، از کدگذاری‌های خاص خود استفاده می‌کنند. این گزینه با نگاشت کدهای نامعتبر به یک جدول کد (codepage) «اختصاصی» در مجموعه یونیکد، نام‌های اشیاء با UTF-8 نامعتبر را دوباره به UTF-8 معتبر تبدیل می‌کند. این گزینه برای کلاینت‌هایی که از UTF-8 به عنوان کدگذاری سیستم‌فایل خود استفاده نمی‌کنند، مفید است.
اگر اطلاعات احراز هویت از طریق متغیرهای محیطی فراهم شده باشد، این سوئیچ بررسی حضور متغیر AWS_SESSION_TOKEN را اجباری می‌کند؛ در غیر این صورت یک خطا برگردانده می‌شود.
این گزینه به s3fs دستور می‌دهد تا درخواست‌های مربوط به باکت‌های پرداخت توسط درخواست‌دهنده (Requester Pays) را فعال کند (مدخل 'x-amz-request-payer=requester' را در سرآیند درخواست قرار می‌دهد).
مسیر فایل mime.types را مشخص می‌کند. اگر این گزینه مشخص نشود، وجود فایل "/etc/mime.types" بررسی شده و آن فایل به عنوان اطلاعات mime بارگذاری می‌شود. اگر این فایل در macOS وجود نداشته باشد، مسیر "/etc/apache2/mime.types" نیز بررسی خواهد شد.
این گزینه یک پروکسی را برای اتصال به سرور S3 مشخص می‌کند. پروکسی را با قالب '[<scheme://]hostname(fqdn)[:<port>]' مشخص کنید. مقدار '<schema>://' قابل حذف است و در صورت حذف، از 'http://' استفاده می‌شود. همچنین، ':<port>' نیز می‌تواند حذف شود. در صورت حذف، درگاه 443 برای طرح HTTPS و در غیر این صورت درگاه 1080 استفاده می‌شود. این گزینه مشابه گزینه '--proxy(-x)' دستور curl و پرچم 'CURLOPT_PROXY' در libcurl است. این گزینه معادل متغیرهای محیطی 'http_proxy'، 'all_proxy' و غیره بوده و نسبت به آن‌ها اولویت دارد.
این گزینه فایلی را مشخص می‌کند که نام کاربری و گذرواژه را برای احراز هویت در پروکسی شرح می‌دهد (هنگامی که پروکسی با طرح HTTP توسط گزینه 'proxy' مشخص شده باشد). نام کاربری و گذرواژه فقط برای طرح HTTP معتبر هستند. اگر پروکسی HTTP نیازی به احراز هویت نداشته باشد، به این گزینه نیازی نیست. نام کاربری و گذرواژه را با نویسه ':' جدا کرده و هر کدام را به‌صورت یک رشته با کدگذاری URL مشخص کنید.
انتخاب نوع آدرس‌های IP مورد استفاده هنگام برقراری اتصال. مقدار پیش‌فرض ('whatever') می‌تواند از آدرس‌های تمامی نسخه‌های IP (شامل IPv4 و IPv6) که سیستم شما مجاز دانسته استفاده کند. اگر 'IPv4' را مشخص کنید، فقط آدرس‌های IPv4 استفاده می‌شوند؛ و هنگامی که 'IPv6' مشخص شود، تنها آدرس‌های IPv6 به کار گرفته خواهند شد.
برنامه s3fs لاگ را در syslog خروجی می‌دهد. متناوباً، اگر s3fs با مشخص کردن گزینه "-f" اجرا شود، لاگ در stdout/stderr خروجی داده خواهد شد. با این گزینه می‌توانید فایل لاگی را که s3fs خروجی می‌دهد مشخص کنید. اگر با این گزینه یک فایل لاگ مشخص کنید، s3fs هنگام دریافت سیگنال SIGHUP فایل لاگ را مجدداً باز خواهد کرد. می‌توانید از سیگنال SIGHUP برای چرخش لاگ‌ها (log rotation) استفاده کنید.
تنظیم سطح پیام‌های اشکال‌زدایی. مقادیر crit (بحرانی)، err (خطا)، warn (هشدار)، info (اطلاعات) را برای سطح اشکال‌زدایی تعیین کنید. سطح پیش‌فرض اشکال‌زدایی critical است. اگر s3fs با گزینه "-d" اجرا شود، سطح اشکال‌زدایی روی information تنظیم می‌شود. هنگامی که s3fs سیگنال SIGUSR2 را دریافت کند، سطح اشکال‌زدایی افزایش می‌یابد.
با مشخص کردن این گزینه، پیام اشکال‌زدایی از کتابخانه libcurl درج می‌شود. برای این پارامتر مقدار "normal" یا "body" را مشخص کنید. اگر پارامتر حذف شود، همانند "normal" خواهد بود. اگر "body" مشخص شود، علاوه بر خروجی پیام اشکال‌زدایی در حالت "normal"، برخی داده‌های بدنه ارتباطات API نیز خروجی داده می‌شوند.
به‌طور پیش‌فرض، برچسب زمان در پیام اشکال‌زدایی درج می‌شود. اگر این گزینه مشخص شود، برچسب زمان در پیام اشکال‌زدایی درج نخواهد شد. این کارکرد مشابه حالتی است که متغیر محیطی "S3FS_MSGTIMESTAMP" بر روی "no" تنظیم شده باشد.
در صورت فعال بودن حافظه موقت (cache)، می‌توانید یکپارچگی فایل کش و فایل اطلاعات آمار (stats) آن را بررسی کنید. با مشخص شدن این گزینه، هنگام ارسال سیگنال SIGUSR1 به فرایند s3fs، وضعیت کش در آن زمان بررسی می‌شود. این گزینه می‌تواند یک مسیر فایل را به عنوان پارامتر دریافت کند تا نتیجه بررسی را در آن فایل خروجی دهد. پارامتر مسیر فایل می‌تواند حذف شود؛ در صورت حذف شدن، نتیجه در stdout یا syslog خروجی داده خواهد شد.
هنگامی که یک فایل یا دایرکتوری ایجاد یا حذف می‌شود (زمانی که inode دایرکتوری والد به‌روزرسانی می‌شود)، مقادیر mtime و ctime دایرکتوری والد به‌روزرسانی می‌شوند. به‌طور پیش‌فرض، آمارهای دایرکتوری والد به‌روزرسانی نمی‌شوند..SS "گزینه‌های حالت ابزار (utility mode options)"
اشیای چندبخشیِ ناقص (multipart incomplete) بارگذاری‌شده در باکت مشخص‌شده را فهرست می‌کند.
اشیای چندبخشی ناقص بارگذاری‌شده در باکت مشخص‌شده را حذف می‌کند. اگر «all» برای این گزینه مشخص شود، تمام اشیای چندبخشی ناقص حذف خواهند شد. اگر هیچ آرگومانی مشخص نکنید، اشیای قدیمی‌تر از ۲۴ ساعت (24H) حذف خواهند شد (این مقدار پیش‌فرض است). می‌توانید یک قالب تاریخ اختیاری مشخص کنید. این مقدار می‌تواند بر حسب سال، ماه، روز، ساعت، دقیقه و ثانیه مشخص شود و به ترتیب با «Y»، «M»، «D»، «h»، «m» و «s» نمایش داده می‌شود؛ برای نمونه، «1Y6M10D12h30m30s».

بیشتر گزینه‌های عمومی سوار کردن (mount) که در 'man mount' شرح داده شده‌اند، پشتیبانی می‌شوند (از جمله ro، rw، suid، nosuid، dev، nodev، exec، noexec، atime، noatime، sync، async و dirsync). سیستم‌های فایل به‌طور پیش‌فرض با «-onodev,nosuid» سوار می‌شوند که تنها توسط یک کاربر دارای دسترسی ویژه (ممتاز) قابل لغو است.
گزینه‌های اختصاصی متعددی برای سوار کردن با FUSE وجود دارد که می‌توان مشخص کرد، مانند allow_other. برای مشاهده مجموعه کامل، پرونده README مربوط به FUSE را ببینید.

هنگام مشخص کردن نقطه پایانی کارگزار (URL endpoint) دقت کنید.

اگر نام باکت شما شامل نقطه («.») است، باید از شیوه درخواست بر اساس مسیر (با استفاده از گزینه «use_path_request_style») استفاده کنید.
همچنین اگر از کارگزاری غیر از Amazon S3 استفاده می‌کنید، باید نقطه پایانی را با گزینه «url» مشخص نمایید. در این حالت، بسته به کارگزاری که استفاده می‌کنید، ممکن است مجبور باشید شیوه درخواست بر اساس مسیر (گزینه «use_path_request_style») را تعیین کنید.

ابزار s3fs برای کارکرد خود به حافظه نهان (کَش) محلی نیاز دارد. می‌توانید با «-o use_cache» یک کَش محلی را فعال کنید، در غیر این صورت s3fs از فایل‌های موقت برای کش کردن درخواست‌های معلق به s3 استفاده می‌کند.
جدا از نیازمندی‌های مطرح‌شده در زیر، توصیه می‌شود به اندازه کافی فضای حافظه نهان یا ذخیره‌سازی موقت نگه دارید تا امکان نگهداری یک نسخه از تمام فایل‌های باز برای خواندن و نوشتن در هر لحظه فراهم باشد.

ابزار s3fs به‌طور خودکار یک کَش محلی از فایل‌ها نگهداری می‌کند. پوشه کَش با پارامتر «-o use_cache» مشخص می‌شود. این تنها یک حافظه نهان محلی است که در هر زمان می‌توان آن را حذف کرد؛ s3fs در صورت نیاز دوباره آن را می‌سازد.
هر زمان که s3fs نیاز به خواندن یا نوشتن فایلی روی S3 داشته باشد، ابتدا فایل را در پوشه کَش ایجاد کرده و روی آن عملیات انجام می‌دهد.
میزان فضای ذخیره‌سازی کَش محلیِ استفاده‌شده را می‌توان به‌طور غیرمستقیم با «-o ensure_diskfree» کنترل کرد.

از آنجا که s3fs همیشه برای فعالیت به مقداری فضای ذخیره‌سازی نیاز دارد، فایل‌های موقتی برای ذخیره درخواست‌های نوشتن ورودی ایجاد می‌کند تا زمانی که اندازه مورد نیاز درخواست s3 برآورده شود و قطعه مربوطه بارگذاری گردد. پس از آن، این داده‌ها در فایل موقت کوتاه (truncate) می‌شوند تا فضای ذخیره‌سازی آزاد گردد.
به ازای هر فایل، برای نوشتن درخواست‌های چندبخشی حداقل به دو برابر اندازه هر بخش (پیش‌فرض 5MB یا «-o multipart_size») فضا نیاز دارید، یا در صورت فعال بودن درخواست‌های تکی («-o nomultipart»)، به فضایی به اندازه کل فایل نیاز خواهد بود.

این بخش به بررسی تنظیماتی برای بهبود عملکرد s3fs می‌پردازد.
در بیشتر موارد، عملکرد بخش پشتیبان (backend) قابل کنترل نیست و بنابراین بخشی از این مبحث به شمار نمی‌آید.
جزئیات استفاده از ذخیره‌سازی محلی در بخش «مصرف فضای ذخیره‌سازی محلی (LOCAL STORAGE CONSUMPTION)» مورد بحث قرار گرفته است.

ابزار s3fs یک برنامه چندریسمانی (multi-threaded) است. بسته به بار کاری، ممکن است از چندین پردازنده و مقدار معینی حافظه استفاده کند. می‌توانید مصرف CPU و حافظه را با ابزار «top» پایش کنید.

ابزار s3fs گزینه‌های متعددی (مانند گزینه «max_thread_count») را برای کنترل رفتار و در نتیجه عملکرد به‌صورت غیرمستقیم ارائه می‌دهد. ترکیب‌های ممکن این گزینه‌ها در ارتباط با پشتیبان‌های گوناگون S3 آن‌قدر متنوع است که هیچ توصیه خاصی جز مقادیر پیش‌فرض وجود ندارد. تنظیمات بهینه فردی را می‌توان از طریق آزمودن و اندازه‌گیری به دست آورد.
دو گزینه «فعال‌سازی کَش منفی» («-o enable_negative_cache») و «غیرفعال‌سازی پشتیبانی از نام‌های جایگزین دایرکتوری» («-o notsup_compat_dir») می‌توانند برای کنترل دسترسی مشترک برنامه‌های مختلف به یک باکت یکسان استفاده شوند:
•
فعال‌سازی کَش منفی («-o enable_negative_cache»)
اگر یک باکت منحصراً توسط یک نمونه از s3fs استفاده می‌شود، می‌توانید با «-o enable_negative_cache» حافظه نهان را برای فایل‌ها و دایرکتوری‌های ناموجود فعال کنید. این کار درخواست‌های مکرر برای بررسی وجود یک شیء را حذف کرده و در زمان و احتمالاً هزینه صرفه‌جویی می‌کند.
•
فعال‌سازی پشتیبانی از نام‌های جایگزین دایرکتوری («-o compat_dir»)
ابزار s3fs اشیای «dir/» را به عنوان دایرکتوری تشخیص می‌دهد. کلاینت‌هایی غیر از s3fs ممکن است از اشیای «dir» یا «dir_$folder$» به عنوان دایرکتوری استفاده کنند، یا ممکن است اشیای دایرکتوری اصلاً وجود نداشته باشند. برای اینکه s3fs بتواند این موارد را به عنوان دایرکتوری شناسایی کند، می‌توانید گزینه «compat_dir» را مشخص کنید.
•
تکمیل اطلاعات فایل و دایرکتوری («-o complement_stat»)
ابزار s3fs از هدر «x-amz-meta-mode header» برای تعیین اینکه آیا یک شیء فایل است یا دایرکتوری، استفاده می‌کند. به همین دلیل، اشیایی که فاقد این هدر هستند ممکن است نتایج مورد انتظار را ارائه ندهند (دایرکتوری نمایش داده نمی‌شود و غیره). با مشخص کردن گزینه «complement_stat»، ابزار s3fs می‌تواند این اطلاعات ویژگی‌های ناموجود را به‌طور خودکار تکمیل کند تا به نتایج مورد نظر برسید.

حداکثر اندازه اشیایی که s3fs می‌تواند مدیریت کند به Amazon S3 بستگی دارد. برای مثال، هنگام استفاده از API تکیِ PUT تا ۵ گیگابایت، و در صورت استفاده از Multipart Upload API تا ۵ ترابایت پشتیبانی می‌شود.
ابزار s3fs از مسیر /etc/mime.types برای «حدس زدن» نوع محتوای «صحیح» (content-type) بر اساس پسوند نام فایل بهره می‌برد. این بدان معناست که می‌توانید یک وب‌سایت را روی S3 کپی کرده و آن را مستقیماً از S3 با انواع محتوای صحیح ارائه دهید!.SH "همچنین ببینید (SEE ALSO)"
fuse(8), mount(8), fusermount(1), fstab(5)

به دلیل محدودیت‌های «سازگاری نهایی» (eventual consistency) در S3، ایجاد فایل ممکن است و گهگاه با شکست مواجه خواهد شد. حتی پس از یک ایجاد موفقیت‌آمیز، خواندن‌های بعدی می‌توانند برای مدت نامعلومی با شکست مواجه شوند، حتی پس از یک یا چند بار خواندن موفق. اگر به اندازه کافی فایل ایجاد کرده و بخوانید، در نهایت با این شکست روبرو خواهید شد. این نقصی در s3fs نیست و چیزی نیست که یک لفاف FUSE مانند s3fs بتواند آن را دور بزند. گزینه retries این مشکل را برطرف نمی‌کند. برنامه شما باید این شکست‌ها را تحمل کرده یا آن‌ها را جبران کند، برای مثال با تلاش مجدد برای ایجاد یا خواندن.

ابزار s3fs توسط Randy Rizun <rrizun@gmail.com> نوشته شده است.

January 2026 S3FS