FLATPAK METADATA(5) flatpak metadata FLATPAK METADATA(5)

flatpak-metadata - اطلاعات مربوط به یک برنامه یا محیط زمان اجرا

فلت‌پک (Flatpak) از پرونده‌های متادیتا برای توصیف برنامه‌ها و محیط‌های زمان اجرا (runtimes) استفاده می‌کند. پرونده metadata برای یک برنامه یا زمان اجرای مستقرشده در دایرکتوری سطح بالای استقرار قرار می‌گیرد. برای نمونه، متادیتای برنامه محلی نصب‌شده org.gnome.Calculator در مسیر ~/.local/share/flatpak/app/org.gnome.Calculator/current/active/metadata قرار دارد.

بیشتر جنبه‌های پیکربندی متادیتا را می‌توان هنگام اجرای برنامه‌ها بازنویسی کرد، چه به صورت موقت از طریق گزینه‌های دستور flatpak run، یا به طور دائمی با دستور flatpak override.

یک پرونده متادیتا که پیکربندی اعمال‌شده و مؤثر را توصیف می‌کند درون سندباکس در حال اجرا در مسیر /.flatpak-info در دسترس است. جهت سازگاری با نسخه‌های قدیمی‌تر فلت‌پک، مسیر /run/user/$UID/flatpak-info یک پیوند نمادین (symlink) به همان پرونده است.

پرونده متادیتا از همان قالب پرونده‌های .ini استفاده می‌کند که در پرونده‌های واحد systemd یا پرونده‌های .desktop برنامه‌ها به کار می‌رود.

متادیتا برای برنامه‌ها با یک گروه [Application] و متادیتا برای محیط‌های زمان اجرا با یک گروه [Runtime] آغاز می‌شود.

کلیدهای زیر می‌توانند در این گروه‌ها حضور داشته باشند:

name (string)

نام برنامه یا محیط زمان اجرا. این کلید اجباری است.

runtime (string)

نام کامل و واجد شرایط محیط زمان اجرایی که توسط برنامه استفاده می‌شود. این کلید برای برنامه‌ها اجباری است.

sdk (string)

نام کامل و واجد شرایط کیت توسعه نرم‌افزار (SDK) که با زمان اجرا مطابقت دارد. در دسترس از نسخه 0.1.

command (string)

دستور جهت اجرا. تنها برای برنامه‌ها کاربرد دارد. در دسترس از نسخه 0.1.

required-flatpak (string list)

نسخه مورد نیاز فلت‌پک برای اجرای این برنامه یا محیط زمان اجرا. برای برنامه‌ها، این مورد از نسخه 0.8.0 در دسترس بود. برای محیط‌های زمان اجرا، این امکان از نسخه 0.9.1 در دسترس بود و به نسخه 0.8.3 برای شاخه 0.8.x بک‌پورت شد.

نسخه‌های فلت‌پک پس از 1.4.3 و 1.2.5 از چندین نسخه در این قسمت پشتیبانی می‌کنند. این ویژگی در صورتی که نیاز به پشتیبانی از قابلیت‌های بک‌پورت‌شده به یک سری پایدار قبلی داشته باشید مفید است. برای نمونه اگر می‌خواهید از قابلیتی استفاده کنید که در نسخه 1.6.0 افزوده شده و به 1.4.4 نیز بک‌پورت شده است، می‌توانید از 1.6.0;1.4.4; استفاده کنید. توجه داشته باشید که نسخه‌های قدیمی‌تر فلت‌پک صرفاً از اولین عنصر موجود در فهرست استفاده می‌کنند، بنابراین بالاترین نسخه را اول قرار دهید.

tags (string list)

برچسب‌هایی برای گنجاندن در AppStream XML. مقادیر معمول مورد استفاده در Flathub شامل beta, stable, proprietary و upstream-maintained است. در دسترس از نسخه 0.4.12.

این گروه منابع مختلف سیستمی را تعیین می‌کند که ممکن است هنگام اجرای برنامه در یک سندباکس فلت‌پک به اشتراک گذاشته شوند.

مجوزهای شرطی (Conditional Permissions)

برخی مجوزها (مانند sockets و devices) از اعطای شرطی پشتیبانی می‌کنند، که در آن دسترسی تنها زمانی فراهم می‌شود که شرایط معینی در زمان اجرا برقرار باشد. این ویژگی به برنامه‌ها امکان می‌دهد با قابلیت‌های گوناگون سیستم و انواع نشست‌ها سازگار شوند. در دسترس از نسخه 1.17.

مجوزهای شرطی از نحو if:PERMISSION:CONDITION در پرونده متادیتا استفاده می‌کنند. برای نمونه، if:wayland:has-wayland دسترسی به سوکت Wayland را تنها در زمان اجرا در یک نشست Wayland اعطا می‌کند.

شرایط زیر پشتیبانی می‌شوند:

true

همیشه به عنوان true ارزیابی می‌شود.

false

همیشه به عنوان false ارزیابی می‌شود.

has-input-device

در صورتی که این نسخه از فلت‌پک از مجوز دستگاه input پشتیبانی کند، true خواهد بود. این مقدار در فلت‌پک 1.15.6 و بالاتر همیشه true است و می‌تواند برای ارائه رفتار جایگزین (fallback) برای نسخه‌های قدیمی‌تر فلت‌پک به کار رود.

has-wayland

در صورتی که نشست میزکار فعلی از Wayland پشتیبانی کند true است.

has-usb-device

در صورتی که این نسخه از فلت‌پک از مجوز دستگاه usb پشتیبانی کند true خواهد بود. این مقدار در فلت‌پک 1.16.0 و بالاتر همیشه true است و می‌تواند برای ارائه رفتار جایگزین برای نسخه‌های قدیمی‌تر فلت‌پک استفاده شود.

has-usb-portal

در صورتی که نشست میزکار فعلی از پورتال USB پشتیبانی کند true است.

شرایط می‌توانند با افزودن پیشوند ! نقیض شوند. برای نمونه، if:x11:!has-wayland دسترسی به سوکت X11 را تنها زمانی اعطا می‌کند که برنامه در نشست Wayland اجرا *نشود*.

می‌توان چندین مجوز شرطی را برای یک منبع یکسان مشخص کرد. در صورتی که هر یک از شرایط مطابقت داشته باشد، مجوز اعطا می‌شود (منطق OR). برای نمونه:

sockets=wayland;if:x11:!has-wayland;if:x11:false

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

sockets=x11;if:x11:!has-wayland;

نسخه‌های قدیمی‌تر فلت‌پک دسترسی X11 را بدون قید و شرط اعطا می‌کنند (زیرا فقط x11 را می‌بینند)، در حالی که نسخه‌های جدیدتر نحو شرطی را شناسایی کرده و دسترسی X11 را تنها در صورت عدم وجود نشست Wayland فراهم می‌آورند.

برای سلب صریح مجوزی که ممکن است در یک لایه پایین‌تر (مانند زمان اجرا یا یک override سراسری) اعطا شده باشد، پیشوند ! را به ابتدای نام مجوز اضافه کنید:

sockets=!x11;

این سلب دسترسی می‌تواند با اعطای شرطی ترکیب شود تا دسترسی غیرشرطی حذف شده و در عین حال دسترسی شرطی ممکن گردد:

sockets=!x11;x11;if:x11:!has-wayland;

این دستور دسترسی غیرشرطی به X11 را رد می‌کند، اما دسترسی شرطی به X11 را در صورت عدم اجرا در نشست Wayland مجاز می‌سازد. تناقض ظاهری بین !x11 و x11 سازگاری رو به عقب را تضمین می‌کند: نسخه‌های قدیمی‌تر فلت‌پک اعطای نهایی x11 را می‌بینند، در حالی که نسخه‌های جدیدتر منطق شرطی را درک می‌نمایند.

تمام کلیدهای موجود در این گروه (و خود گروه) اختیاری هستند.

کلیدهای پشتیبانی‌شده در این گروه عبارتند از:

shared (list)

فهرستی از زیرسیستم‌ها جهت به‌اشتراک‌گذاری با سیستم میزبان. زیرسیستم‌های ممکن: network, ipc. در دسترس از نسخه 0.3.

این گزینه از مجوزهای شرطی پشتیبانی می‌کند. برای جزئیات در مورد نحوه به‌اشتراک‌گذاری شرطی دسترسی به زیرسیستم بر اساس شرایط زمان اجرا به مجوزهای شرطی (Conditional Permissions) مراجعه کنید.

sockets (list)

فهرستی از سوکت‌های شناخته‌شده جهت در دسترس قرار دادن در سندباکس. سوکت‌های ممکن: x11, wayland, fallback-x11, pulseaudio, session-bus, system-bus, ssh-auth, pcsc, cups, gpg-agent, inherit-wayland-socket. هنگام در دسترس قرار دادن یک سوکت، فلت‌پک همچنین متغیرهای محیطی شناخته‌شده‌ای مانند DISPLAY یا DBUS_SYSTEM_BUS_ADDRESS را تنظیم می‌کند تا به برنامه امکان دهد سوکت‌هایی را که در مکان ثابتی قرار ندارند بیابد. در دسترس از نسخه 0.3.

این گزینه از مجوزهای شرطی پشتیبانی می‌کند. برای جزئیات نحوه اعطای شرطی دسترسی به سوکت بر اساس شرایط زمان اجرا به مجوزهای شرطی (Conditional Permissions) مراجعه فرمایید.

devices (list)

فهرستی از دستگاه‌ها جهت در دسترس قرار دادن در سندباکس. این گزینه صرفاً گره‌های دستگاه (device nodes) را نمایان می‌سازد و هیچ مجوزی را که کاربر از قبل نداشته باشد اعطا نمی‌کند. مقادیر ممکن:

dri

پردازش و گرافیک GPU در (/dev/dri)، شامل دستگاه‌های رندر و پردازش اختصاصی سازندگان مختلف. در دسترس از نسخه 0.3.

input

دستگاه‌های ورودی (/dev/input). در دسترس از نسخه 1.15.6.

usb

گذرگاه دستگاه USB (تمام گره‌های دستگاه در زیر /dev/bus/usb). در دسترس از نسخه 1.15.11.

kvm

مجازی‌سازی (/dev/kvm). در دسترس از نسخه 0.6.12.

all

تمامی گره‌های دستگاه در /dev، اما به جز /dev/shm (که به طور جداگانه مشخص می‌شود). در دسترس از نسخه 0.6.6.

shm

دسترسی به /dev/shm میزبان (/dev/shm). در دسترس از نسخه 1.6.1.

این گزینه از مجوزهای شرطی پشتیبانی می‌کند. برای جزئیات بیشتر به مجوزهای شرطی (Conditional Permissions) مراجعه فرمایید.

filesystems (list)

فهرستی از زیرمجموعه‌های سیستم‌فایل جهت در دسترس قرار دادن برای برنامه. مقادیر ممکن:

home

کل پوشه خانگی (home directory). در دسترس از نسخه 0.3.

home/path

نام مستعار برای ~/path. در دسترس از نسخه 1.10. برای سازگاری بهتر با نسخه‌های قدیمی‌تر فلت‌پک، بهتر است آن را به صورت ~/path بنویسید.

host

کل سیستم‌فایل میزبان، به جز پوشه‌هایی که به صورت ویژه توسط فلت‌پک مدیریت می‌شوند. به طور خاص، مسیرهای /home, /media, /opt, /run/media و /srv را در صورت وجود به اشتراک می‌گذارد.

مسیر /dev به اشتراک گذاشته نمی‌شود: به جای آن از devices=all; استفاده کنید.

بخش‌هایی از /sys همیشه به اشتراک گذاشته می‌شوند. این گزینه پرونده‌های بیشتری را در /sys در دسترس قرار نمی‌دهد.

علاوه بر این، این کلمه کلیدی تمامی پوشه‌های مشابه در /run/host را همانند کلمات کلیدی host-os و host-etc ارائه می‌دهد. اگر این کلمه کلیدی همراه با یکی از کلمات کلیدی host- استفاده شود، هر سطح دسترسی که بالاتر (مجازتر) باشد برای پوشه‌های موجود در /run/host اعمال خواهد شد؛ برای نمونه، host:rw;host-os:ro; معادل با host:rw; است.

این پوشه‌های رزروشده دیگر در حال حاضر مستثنی هستند: /app, /bin, /boot, /efi, /etc, /lib, /lib32, /lib64, /proc, /root, /run, /sbin, /tmp, /usr, /var.

در دسترس از نسخه 0.3.

host-os

کتابخانه‌ها، برنامه‌های اجرایی و داده‌های ایستای سیستم‌عامل میزبان از /usr و پوشه‌های مرتبط /bin, /lib, /lib32, /lib64, /sbin. علاوه بر این، این کلمه کلیدی دسترسی به زیرمجموعه‌ای از /etc را که با کتابخانه‌ها و برنامه‌های اجرایی بسته‌بندی‌شده مرتبط است فراهم می‌کند، حتی اگر از کلمه کلیدی host-etc استفاده نشده باشد: /etc/ld.so.cache (مورد استفاده توسط پیونددهنده پویا) و /etc/alternatives (در سیستم‌عامل‌هایی که از آن استفاده می‌کنند، مانند دبیان).

برای جلوگیری از تداخل با زمان اجرای فلت‌پک، این موارد در سندباکس در مسیرهای /run/host/usr, /run/host/etc/ld.so.cache و موارد مشابه سوار می‌شوند.

در دسترس از نسخه 1.7.

host-etc

پیکربندی سیستم‌عامل میزبان از مسیر /etc.

جهت جلوگیری از تداخل با زمان اجرای فلت‌پک، این مسیر در سندباکس در /run/host/etc سوار می‌شود.

در دسترس از نسخه 1.7.

host-root

کل سیستم‌عامل میزبان به صورت کامل.

جهت جلوگیری از تداخل با زمان اجرای فلت‌پک، این مسیر در سندباکس در /run/host/root سوار می‌شود.

این مجوز فقط به عنوان آخرین راه‌حل در شرایطی در نظر گرفته شده است که هیچ جایگزین ممکنی با سایر مجوزهای سیستم‌فایل برای برنامه‌هایی که به کل سیستم‌فایل ریشه میزبان نیاز دارند وجود نداشته باشد.

لطفاً توجه داشته باشید که دنبال کردن ساده پیوندهای نمادین زیر /run/host/root منجر به مسیر اشتباه خواهد شد. برای نمونه، استفاده از realpath() نادرست است. در عوض، برنامه‌ها باید روشی را برای دنبال کردن پیوندهای نمادین پیاده‌سازی کنند که رفتاری مطابق با chroot شدن در /run/host/root داشته باشد.

چند روش برای این کار وجود دارد. هسته‌های جدید از فراخوانی openat2()[1] همراه با RESOLVE_IN_ROOT پشتیبانی می‌کنند. برای یک راه‌حل سازگارتر با پشتیبانی از هسته‌های قدیمی‌تر، پیاده‌سازی ارائه‌شده در steam-runtime-tools[2] را به عنوان یک نمونه ببینید.

در دسترس از نسخه 1.17.

xdg-desktop, xdg-documents, xdg-download, xdg-music, xdg-pictures, xdg-public-share, xdg-videos, xdg-templates

پوشه‌های ویژه freedesktop.org[3]. در دسترس از نسخه 0.3.

xdg-desktop/path, xdg-documents/path, etc.

زیرپوشه‌های پوشه‌های ویژه freedesktop.org. در دسترس از نسخه 0.4.13.

xdg-cache, xdg-config, xdg-data

پوشه‌های تعریف‌شده توسط مشخصات دایرکتوری پایه freedesktop.org[4]. در دسترس از نسخه 0.6.14.

xdg-cache/path, xdg-config/path, xdg-data/path

زیرپوشه‌های پوشه‌های تعریف‌شده در مشخصات دایرکتوری پایه freedesktop.org. در دسترس از نسخه 0.6.14.

xdg-run/path

زیرپوشه‌های XDG_RUNTIME_DIR تعریف‌شده در مشخصات دایرکتوری پایه freedesktop.org. توجه داشته باشید که xdg-run به تنهایی پشتیبانی نمی‌شود. در دسترس از نسخه 0.4.13.

/path

یک مسیر مطلق دلخواه. در دسترس از نسخه 0.3.

~/path

یک مسیر دلخواه وابسته به پوشه خانگی (home). در دسترس از نسخه 0.3.

~

همانند home. در دسترس از نسخه 1.10. برای سازگاری بهتر با نسخه‌های قدیمی‌تر فلت‌پک، بهتر است آن را به شکل home بنویسید.

یکی از موارد بالا همراه با :ro

پوشه مشخص‌شده را به صورت فقط‌خواندنی در دسترس قرار می‌دهد.

یکی از موارد بالا همراه با :rw

پوشه مشخص‌شده را به صورت خواندن/نوشتن در دسترس قرار می‌دهد. این حالت پیش‌فرض است.

یکی از موارد بالا همراه با :create

پوشه مشخص‌شده را به صورت خواندن/نوشتن در دسترس قرار می‌دهد و در صورتی که از قبل وجود نداشته باشد، آن را ایجاد می‌کند.

persistent (list)

فهرستی از مسیرهای وابسته به homedir برای در دسترس قرار دادن در مسیر متناظر در پوشه خانگی اختصاصی برنامه، که اجازه می‌دهد این مکان‌ها برای داده‌های ماندگار در زمانی که برنامه به پوشه خانگی واقعی دسترسی ندارد استفاده شوند. برای نمونه، ماندگار کردن ".myapp" باعث می‌شود "~/.myapp" در سندباکس به صورت یک پیوند متصل (bind mount) به "~/.var/app/org.my.App/.myapp" درآید، بنابراین به برنامه بدون نیاز به تغییر اجازه می‌دهد تا داده‌ها را در مکان اختصاصی برنامه ذخیره کند. در دسترس از نسخه 0.3.

features (list)

فهرستی از ویژگی‌های فعال یا غیرفعال برای برنامه، در حال حاضر از فهرست زیر:

devel

اجازه دادن به فراخوانی‌های سیستمی مورد استفاده توسط ابزارهای توسعه مانند perf, strace و gdb. در دسترس از نسخه 0.6.10.

multiarch

اجازه اجرای باینری‌های چندمعماری/چندکتابخانه‌ای (multilib/multiarch)، برای نمونه باینری‌های i386 در یک محیط x86_64. در دسترس از نسخه 0.6.12.

bluetooth

اجازه استفاده از سوکت‌های بلوتوث (AF_BLUETOOTH) به برنامه. توجه داشته باشید برای اینکه بلوتوث به طور کامل کار کند، باید به شبکه نیز دسترسی داشته باشید. در دسترس از نسخه 0.11.8.

canbus

اجازه استفاده از سوکت‌های canbus (AF_CAN) به برنامه. توجه داشته باشید که برای کارکرد این قابلیت باید دسترسی به شبکه نیز داشته باشید. در دسترس از نسخه 1.0.3.

per-app-dev-shm

به اشتراک‌گذاری یک نمونه واحد از /dev/shm میان تمامی نمونه‌های این برنامه که توسط شناسه کاربری یکسان اجرا می‌شوند، از جمله زیرسندباکس‌ها. اگر برنامه دارای مجوز دستگاه shm در فهرست devices خود باشد، این پرچم نادیده گرفته می‌شود. در دسترس از نسخه 1.12.0.

یک ویژگی می‌تواند با پیشوند ! مشخص شود تا نشان‌دهنده نبود آن ویژگی باشد، برای نمونه !devel در صورتی که توسعه و اشکال‌زدایی مجاز نباشد.

این گزینه از مجوزهای شرطی پشتیبانی می‌کند. برای جزئیات در مورد نحوه مجاز کردن ویژگی‌ها به صورت شرطی بر اساس شرایط زمان اجرا به مجوزهای شرطی (Conditional Permissions) مراجعه کنید.

unset-environment (list)

فهرستی از نام‌های متغیرهای محیطی که باید لغو (unset) شوند. توجه داشته باشید که متغیرهای محیطی که باید روی یک مقدار (احتمالاً خالی) تنظیم شوند، به جای اینجا در گروه [Environment] ظاهر می‌شوند.

این گروه فقط در /.flatpak-info برای یک برنامه در حال اجرا ظاهر می‌شود و در پرونده‌های متادیتای نوشته‌شده توسط نویسندگان برنامه وجود ندارد. این گروه توسط خود فلت‌پک پر می‌شود.

instance-id (string)

شناسه نمونه در حال اجرا. این شماره به عنوان نام پوشه در XDG_RUNTIME_DIR/.flatpak استفاده می‌شود که فلت‌پک اطلاعات مربوط به این نمونه را در آن ذخیره می‌کند.

instance-path (string)

مسیر مطلق در سیستم میزبان برای فضای ذخیره‌سازی ماندگار برنامه در $HOME/.var.

app-path (string)

مسیر مطلق پرونده‌های برنامه در سیستم میزبان، به همان صورت که در /app درون کانتینر سوار شده است. در دسترس از نسخه 0.6.10.

از نسخه 1.12.0، اگر flatpak run با گزینه --app-path اجرا شده باشد، این کلید مسیر مطلق هر پرونده‌ای را که روی /app سوار شده است می‌دهد، حتی اگر با پرونده‌های عادی برنامه تفاوت داشته باشد.

اگر flatpak run با گزینه --app-path= اجرا شود (که منجر به سوار شدن یک پوشه خالی روی /app می‌شود)، مقدار آن برابر با رشته خالی تنظیم می‌گردد.

original-app-path (string)

اگر flatpak run با گزینه --app-path اجرا شده باشد، این کلید مسیر مطلق پرونده‌های اصلی برنامه را به شکلی که در /run/parent/app درون کانتینر سوار شده است ارائه می‌دهد. در دسترس از نسخه 1.12.0.

اگر این کلید وجود نداشته باشد، پرونده‌های برنامه توسط app-path مشخص می‌شوند.

app-commit (string)

شناسه کامیت (commit ID) برنامه‌ای که در حال اجرا است. نام پرونده مربوط به استقرار این کامیت در صورت وجود در original-app-path یا در غیر این صورت در app-path یافت می‌شود.

app-extensions (list of strings)

فهرستی از افزونه‌های برنامه که در نمونه در حال اجرا سوار شده‌اند. قالب هر آیتم فهرست به صورت EXTENSION_ID=COMMIT است. اگر original-app-path موجود باشد، افزونه‌ها در زیر /run/parent/app سوار می‌شوند؛ در غیر این صورت، در زیر /app سوار خواهند شد.

branch (string)

شاخه برنامه، برای نمونه stable. در دسترس از نسخه 0.6.10.

arch (string)

معماری نمونه در حال اجرا.

flatpak-version (string)

شماره نسخه فلت‌پکی که این برنامه را اجرا کرده است. در دسترس از نسخه 0.6.11.

runtime-path (string)

مسیر مطلق پرونده‌های زمان اجرای برنامه در سیستم میزبان، به همان شکلی که در /usr درون کانتینر سوار شده است. در دسترس از نسخه 0.6.10.

از نسخه 1.12.0، اگر flatpak run با گزینه --usr-path اجرا شده باشد، این کلید مسیر مطلق هر پرونده‌ای را که در /usr سوار شده است نشان می‌دهد، حتی اگر با پرونده‌های عادی زمان اجرا تفاوت داشته باشد.

original-runtime-path (string)

اگر flatpak run با گزینه --runtime-path اجرا شده باشد، این کلید مسیر مطلق زمان اجرای اصلی برنامه را به گونه‌ای که در /run/parent/usr درون کانتینر سوار شده است ارائه می‌دهد. در دسترس از نسخه 1.12.0.

اگر این کلید وجود نداشته باشد، پرونده‌های زمان اجرا توسط runtime-path مشخص می‌شوند.

runtime-commit (string)

شناسه کامیت محیط زمان اجرایی که استفاده می‌شود. نام پرونده مربوط به استقرار این کامیت در صورت وجود در original-runtime-path یا در غیر این صورت در runtime-path یافت می‌شود.

runtime-extensions (list of strings)

فهرستی از افزونه‌های زمان اجرا که در نمونه در حال اجرا سوار شده‌اند. قالب هر آیتم فهرست به صورت EXTENSION_ID=COMMIT است. اگر original-app-path موجود باشد، افزونه‌ها در زیر /run/parent/usr سوار می‌شوند؛ در غیر این صورت در زیر /usr سوار خواهند شد.

extra-args (string)

آرگومان‌های اضافی که به flatpak run ارسال شده‌اند.

sandbox (boolean)

مشخص می‌کند که آیا گزینه --sandbox به flatpak run ارسال شده است یا خیر.

build (boolean)

مشخص می‌کند که آیا این نمونه توسط flatpak build ایجاد شده است یا خیر.

session-bus-proxy (boolean)

در صورتی که این برنامه نتواند مستقیماً به گذرگاه نشست D-Bus دسترسی پیدا کند (یا از طریق یک پروکسی متصل شود، یا اصلاً به گذرگاه نشست دسترسی نداشته باشد) مقدار true دارد. در دسترس از نسخه 0.8.0.

system-bus-proxy (boolean)

در صورتی که این برنامه نتواند مستقیماً به گذرگاه سیستم D-Bus دسترسی یابد (یا از طریق پروکسی باشد، یا اصلاً دسترسی نداشته باشد) مقدار true دارد. در دسترس از نسخه 0.8.0.

اگر کلید sockets دسترسی کامل به گذرگاه نشست D-Bus را ندهد، فلت‌پک دسترسی فیلترشده را فراهم می‌کند.

سیاست پیش‌فرض برای گذرگاه نشست فقط به برنامه اجازه می‌دهد شناسه برنامه خود، نام‌های فرعی آن، و شناسه برنامه خود را به عنوان یک نام فرعی از org.mpris.MediaPlayer2 در اختیار (مالکیت) داشته باشد. برای نمونه اگر برنامه org.my.App نامیده شود، تنها می‌تواند مالک org.my.App, org.my.App.* و org.mpris.MediaPlayer2.org.my.App باشد. این برنامه تنها مجاز است با نام‌های منطبق بر این الگوها، بعلاوه خود گذرگاه (org.freedesktop.DBus) و APIهای پورتال (نام‌های گذرگاه به فرم org.freedesktop.portal.*) ارتباط برقرار کند.

علاوه بر این، برنامه همیشه مجاز است به پیام‌های ارسال‌شده به آن پاسخ دهد و سیگنال‌های عمومی (broadcast) منتشر کند (اما این سیگنال‌ها به سایر برنامه‌های سندباکس‌شده نمی‌رسند مگر اینکه اجازه صحبت با برنامه شما را داشته باشند).

اگر گروه [Session Bus Policy] حضور داشته باشد، خط‌مشی دسترسی به گذرگاه نشست را فراهم می‌سازد.

هر کلید در این گروه شکلی از یک نام گذرگاه D-Bus یا پیشوندی از آن دارد، برای نمونه org.gnome.SessionManager یا org.freedesktop.portal.*.

مقادیر ممکن برای یک مدخل، به ترتیب افزایش سطح دسترسی به شرح زیر هستند. هر مقدار شامل تمام دسترسی‌های مقادیر پایین‌تر نیز می‌باشد:

none

نام گذرگاه برای برنامه نامرئی است. در دسترس از نسخه 0.2.

see

نام گذرگاه می‌تواند توسط برنامه شمارش (enumerate) شود. در دسترس از نسخه 0.2.

talk

برنامه می‌تواند پیام‌هایی به نام گذرگاه ارسال کرده و پاسخ‌ها و سیگنال‌ها را از آن دریافت کند. در دسترس از نسخه 0.2.

own

برنامه می‌تواند مالک نام گذرگاه شود. در دسترس از نسخه 0.2.

اگر کلید sockets دسترسی کامل به گذرگاه سیستم D-Bus را مجاز نداند، فلت‌پک گذرگاه سیستم را در دسترس قرار نمی‌دهد مگر اینکه گروه [System Bus Policy] حضور داشته باشد و خط‌مشی دسترسی فیلترشده را فراهم کند. در دسترس از نسخه 0.2.

مدخل‌های این گروه همانند گروه [Session Bus Policy] هستند. با این حال، برنامه به طور پیش‌فرض هیچ مجوزی ندارد.

گروه [Environment] متغیرهای محیطی را برای مقداردهی هنگام اجرای برنامه تعیین می‌کند. در دسترس از نسخه 0.3.

مدخل‌های موجود در این گروه به شکل VAR=VALUE هستند که در آن VAR نام متغیر محیطی است که باید تنظیم شود.

توجه داشته باشید که متغیرهای محیطی همچنین می‌توانند با درج نام آن‌ها در مدخل unset-environment از گروه [Context]، لغو (حذف از محیط) شوند.

محیط‌های زمان اجرا و برنامه‌ها می‌توانند نقاط توسعه (extension points) تعریف کنند، که به زمان‌های اجرای اضافی و اختیاری اجازه می‌دهد در صورت حضور در سیستم، در یک مکان مشخص در درون سندباکس سوار شوند. کاربردهای متداول نقاط توسعه شامل ترجمه‌ها برای برنامه‌ها یا اطلاعات اشکال‌زدایی (debuginfo) برای کیت‌های توسعه (SDKها) است. نام نقطه توسعه به عنوان بخشی از عنوان گروه مشخص می‌شود. از نسخه 0.11.4، در صورتی که مایل باشید از پیکربندی‌های گوناگون (مثلاً نسخه‌های مختلف) یک افزونه به طور همزمان استفاده کنید، نام می‌تواند اختیاری شامل یک تگ در نحو ref به صورت name@tag باشد. مقدار "tag" در عمل نادیده گرفته می‌شود، اما برای این که یک نام افزونه بتواند بیش از یک بار مشخص شود ضروری است.

directory (string)

مسیر نسبی که افزونه در آن درون سندباکس سوار خواهد شد. اگر نقطه توسعه برای یک برنامه باشد مسیر نسبت به /app است، در غیر این صورت نسبت به /usr خواهد بود. این کلید اجباری است. در دسترس از نسخه 0.1.

version (string)

شاخه‌ای که باید هنگام جستجو برای افزونه استفاده شود. در صورت عدم تعیین، پیش‌فرض شاخه برنامه یا زمان اجرایی است که نقطه توسعه برای آن تعریف شده است. در دسترس از نسخه 0.4.1.

versions (string)

شاخه‌هایی که هنگام جستجو برای افزونه باید استفاده شوند. در صورت عدم تعیین، پیش‌فرض شاخه برنامه یا زمان اجرای مربوطه است. در دسترس از نسخه 0.9.1 و بک‌پورت‌شده به شاخه 0.8.x در نسخه 0.8.4.

add-ld-path (string)

مسیری نسبت به دایرکتوری نقطه توسعه که به LD_LIBRARY_PATH اضافه خواهد شد. در دسترس از نسخه 0.9.1 و بک‌پورت‌شده به شاخه 0.8.x در نسخه 0.8.3.

merge-dirs (string)

فهرستی از مسیرهای نسبی پوشه‌های زیر دایرکتوری نقطه توسعه که ادغام خواهند شد. در دسترس از نسخه 0.9.1 و بک‌پورت‌شده به شاخه 0.8.x در نسخه 0.8.3.

download-if (string)

شرطی که برای دانلود خودکار افزونه باید برقرار (true) باشد. از نسخه 1.1.1 از چندین شرط جداشده با سمیکالن پشتیبانی می‌کند.

شرایط پشتیبانی‌شده عبارتند از:

active-gl-driver

در صورتی که نام درایور فعال GL با نام پایه نقطه توسعه تطابق داشته باشد true است. در دسترس از نسخه 0.9.1 و بک‌پورت‌شده به شاخه 0.8.x در نسخه 0.8.3.

active-gtk-theme

در صورتی که نام پوسته فعلی GTK (از طریق تنظیمات org.gnome.desktop.interface GSetting) با نام پایه نقطه توسعه تطابق داشته باشد true است. افزوده شده در نسخه 0.10.1.

have-intel-gpu

در صورتی که ماژول هسته i915 بارگذاری شده باشد true است. افزوده شده در نسخه 0.10.1.

have-kernel-module-*

در صورتی که پسوند (حساس به بزرگی و کوچکی حروف) در /proc/modules یافت شود true است. برای نمونه have-kernel-module-nvidia. افزوده شده در نسخه 1.13.1.

on-xdg-desktop-*

در صورتی که پسوند (بدون حساسیت به بزرگی و کوچکی حروف) در متغیر محیطی XDG_CURRENT_DESKTOP موجود باشد true است. برای نمونه on-xdg-desktop-GNOME-classic. افزوده شده در نسخه 1.1.1.

autoprune-unless (string)

شرطی که برای اینکه افزونه هنگام هرس (pruning) بلااستفاده تلقی نشود، باید نادرست (false) باشد. برای نمونه، دستورات flatpak uninstall --unused و flatpak update از این اطلاعات استفاده می‌کنند. تنها مقدار شناخته‌شده فعلی active-gl-driver است، که در صورتی که نام درایور فعال GL با نام پایه نقطه توسعه تطابق داشته باشد true است. در دسترس از نسخه 0.11.8.

enable-if (string)

شرطی که برای فعال شدن افزونه باید برقرار (true) باشد. از نسخه 1.1.1 از چندین شرط جداشده با سمیکالن پشتیبانی می‌کند. برای شرایط موجود به download-if مراجعه فرمایید.

subdirectory-suffix (string)

پسوندی که به انتهای نام پوشه اضافه می‌شود. این مورد زمانی بسیار کاربردی است که طرح نام‌گذاری نقطه توسعه "معکوس" باشد. برای نمونه، یک نقطه توسعه برای پوسته‌های GTK+ به صورت /usr/share/themes/$NAME/gtk-3.0 خواهد بود، که می‌تواند با استفاده از subdirectory-suffix=gtk-3.0 محقق شود. در دسترس از نسخه 0.9.1 و بک‌پورت‌شده به شاخه 0.8.x در نسخه 0.8.3.

subdirectories (boolean)

اگر این کلید روی true تنظیم شود، فلت‌پک به دنبال افزونه‌هایی خواهد گشت که نام آن‌ها پیشوندی از نام نقطه توسعه باشد، و آن‌ها را در نام متناظر در زیرپوشه سوار خواهد کرد. در دسترس از نسخه 0.1.

no-autodownload (boolean)

مشخص می‌کند که آیا هنگام به‌روزرسانی یا نصب یک برنامه یا زمان اجرای «مرتبط»، افزونه‌های منطبق با این نقطه توسعه به طور خودکار بارگیری شوند یا خیر. در دسترس از نسخه 0.6.7.

locale-subset (boolean)

اگر تنظیم شود، افزونه‌ها به طور پیش‌فرض بر اساس محلی‌های (locales) پیکربندی‌شده فعلی به صورت جزئی دانلود می‌شوند. این بدان معناست که محتوای افزونه باید مجموعه‌ای از پوشه‌ها با کد زبان به عنوان نام باشد. در دسترس از نسخه 0.9.13 (و 0.6.6 برای هر افزونه با نام *.Locale)

autodelete (boolean)

مشخص می‌کند که آیا هنگام حذف یک برنامه یا محیط زمان اجرای مرتبط، افزونه‌های منطبق با این نقطه توسعه نیز به صورت خودکار حذف شوند یا خیر. در دسترس از نسخه 0.6.7.

collection-id (string)

شناسه مجموعه‌ای که این نقطه توسعه به آن تعلق دارد. در صورت عدم تعیین، به طور پیش‌فرض برابر با شناسه مجموعه برنامه یا محیط زمان اجرای مربوطه خواهد بود. در حال حاضر، نقاط توسعه باید در همان مجموعه‌ای باشند که برنامه یا زمان اجرای مربوط به آن قرار دارد. در دسترس از نسخه 0.99.1.

این گروه اختیاری ممکن است در صورتی که محیط زمان اجرا خود یک افزونه باشد، حضور داشته باشد.

ref (string)

شناسه مرجع (ref) زمان اجرا یا برنامه‌ای که این افزونه به آن تعلق دارد. در دسترس از نسخه 0.9.1.

runtime (string)

محیط زمان اجرایی که این افزونه درون آن قرار خواهد گرفت. اگر یک افزونه برنامه باشد، این مقدار همان زمان اجرای برنامه است؛ در غیر این صورت، این مقدار همسان با ref و بدون پیشوند runtime/ است. در دسترس از نسخه 1.5.0.

priority (integer)

اولویتی که هنگام جستجو برای بهترین تطابق به این افزونه داده می‌شود. پیش‌فرض 0 است. در دسترس از نسخه 0.9.1 و بک‌پورت‌شده به شاخه 0.8.x در نسخه 0.8.3.

tag (string)

نام تگی که باید هنگام جستجو برای نقطه سوار شدن این افزونه در فلت‌پک والد استفاده شود. در دسترس از نسخه 0.11.4.

این گروه اختیاری ممکن است در صورتی که زمان اجرا یا برنامه از داده‌های اضافی استفاده کند که به صورت جداگانه بارگیری می‌شوند، حضور داشته باشد. داده‌های این گروه با کلید xa.extra-data-sources در خلاصه مخزن ادغام می‌شوند.

اگر چندین منبع داده اضافی وجود داشته باشد، کلیدهای uri، size و checksum آن‌ها با استفاده از پسوند یکسان گروه‌بندی می‌شوند. اگر فقط یک منبع داده اضافی وجود داشته باشد، می‌توان پسوند را حذف کرد.

NoRuntime (boolean)

مشخص می‌کند که آیا محیط زمان اجرا هنگام اجرای اسکریپت /app/bin/apply_extra سوار شود یا خیر. مقدار پیش‌فرض true است، یعنی زمان اجرا سوار نمی‌شود. در دسترس از نسخه 0.9.1 و بک‌پورت‌شده به شاخه 0.8.x در نسخه 0.8.4.

uriX (string)

نشانی اینترنتی (URI) برای منبع داده اضافی X. تنها طرح‌های URI پشتیبانی‌شده http و https هستند. در دسترس از نسخه 0.6.13.

sizeX (integer)

اندازه منبع داده اضافی X. در دسترس از نسخه 0.6.13.

checksumX (string)

مقدار جمع کنترلی sha256 برای منبع داده اضافی X. در دسترس از نسخه 0.6.13.

زیرسیستم‌ها می‌توانند خط‌مشی‌های خود را تعریف کنند تا در گروهی قرار گیرند که نام آن این قالب را دارد. مقادیر آن‌ها به عنوان فهرست‌هایی تلقی می‌شوند که در آن‌ها می‌توان مفهوم اعضا را با پیشوند ! به ابتدای مقدار نفی کرد. آن‌ها به صورت دیگری توسط فلت‌پک تجزیه نمی‌شوند. در دسترس از نسخه 0.6.13.

دستگاه‌های USB می‌توانند همان‌گونه که توسط کلیدهای این گروه مشخص شده است، توسط پورتال USB قابل شمارش یا پنهان باشند. شناسه‌های تولیدکننده و محصول توسط فلت‌پک اعتبارسنجی می‌شوند، اما به شکل دیگری استفاده یا تجزیه نمی‌گردند. این کار صرفاً مجوز شمارش دستگاه USB را برای استفاده توسط پورتال اعطا می‌کند و به خودی خود دسترسی به دستگاه‌ها را فراهم نمی‌سازد. در دسترس از نسخه 1.15.11.

enumerable-devices (string list)

فهرستی از دستگاه‌های USB قابل شمارش. هر عضو دارای نحوی یکسان با آرگومان‌های `--usb` است. در دسترس از نسخه 1.15.11.

hidden-devices (string list)

فهرستی از دستگاه‌های USB پنهان، یعنی برای حذف از فهرست دستگاه‌های قابل شمارش. هر عضو دارای نحو یکسانی با آرگومان‌های `--nousb` است. دستگاه‌های پنهان نسبت به دستگاه‌های قابل شمارش اولویت دارند. در دسترس از نسخه 1.15.11.

[Application]
name=org.gnome.Calculator
runtime=org.gnome.Platform/x86_64/3.20
sdk=org.gnome.Sdk/x86_64/3.20
command=gnome-calculator
[Context]
shared=network;ipc;
sockets=x11;wayland;
filesystems=xdg-run/dconf;~/.config/dconf:ro;
[Session Bus Policy]
ca.desrt.dconf=talk
[Environment]
DCONF_USER_CONFIG_DIR=.config/dconf
[USB Devices]
enumerable-devices=0fd9:*;
hidden-devices=0fd9:0063;
[Extension org.gnome.Calculator.Locale]
directory=share/runtime/locale
subdirectories=true
[Extension org.gnome.Calculator.Debug]
directory=lib/debug

مثال استفاده از مجوزهای شرطی برای پشتیبانی از حالت جایگزین (fallback) از Wayland به X11:

[Application]
name=org.example.App
runtime=org.gnome.Platform/x86_64/3.20
sdk=org.gnome.Sdk/x86_64/3.20
[Context]
shared=network;ipc;
sockets=wayland;x11;if:x11:!has-wayland;

در این مثال، برنامه در صورت اجرا در یک نشست Wayland همیشه به سوکت Wayland دسترسی خواهد داشت. سوکت X11 تنها در صورتی در دسترس است که برنامه در یک نشست Wayland اجرا نشود (!has-wayland).

flatpak(1), flatpak-run(1), flatpak-override(1)

1.
openat2()
https://man7.org/linux/man-pages/man2/openat2.2.html
2.
steam-runtime-tools
https://gitlab.steamos.cloud/steamrt/steam-runtime-tools/-/blob/65adfdd5fc812aeb5f33986755f6ff72c9612afa/steam-runtime-tools/resolve-in-sysroot.c
3.
freedesktop.org special directories
https://www.freedesktop.org/wiki/Software/xdg-user-dirs
4.
freedesktop.org Base Directory Specification
https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
flatpak