نام (NAME)

org.freedesktop.home1 - رابط کاربری D-Bus سرویس دایرکتوری خانگی کاربر (systemd-homed)

توضیحات (DESCRIPTION)

systemd-homed.service(8) یک سرویس سیستمی است که می‌تواند برای ایجاد، حذف، تغییر یا بازرسی محدوده‌ها و دایرکتوری‌های خانگی به کار رود. این صفحه رابط کاربری D-Bus را شرح می‌دهد.

رابط D-BUS (THE D-BUS INTERFACE)

شیء مدیر (THE MANAGER OBJECT)

این سرویس رابط‌های زیر را روی شیء Manager در گذرگاه ارائه می‌دهد:

node /org/freedesktop/home1 {
  interface org.freedesktop.home1.Manager {
    methods:
      GetHomeByName(in  s user_name,
                    out u uid,
                    out s home_state,
                    out u gid,
                    out s real_name,
                    out s home_directory,
                    out s shell,
                    out o bus_path);
      GetHomeByUID(in  u uid,
                   out s user_name,
                   out s home_state,
                   out u gid,
                   out s real_name,
                   out s home_directory,
                   out s shell,
                   out o bus_path);
      GetUserRecordByName(in  s user_name,
                          out s user_record,
                          out b incomplete,
                          out o bus_path);
      GetUserRecordByUID(in  u uid,
                         out s user_record,
                         out b incomplete,
                         out o bus_path);
      ListHomes(out a(susussso) home_areas);
      ActivateHome(in  s user_name,
                   in  s secret);
      ActivateHomeIfReferenced(in  s user_name,
                               in  s secret);
      @org.freedesktop.systemd1.Privileged("true")
      DeactivateHome(in  s user_name);
      RegisterHome(in  s user_record);
      AdoptHome(in  s image_path,
                in  t flags);
      UnregisterHome(in  s user_name);
      CreateHome(in  s user_record);
      CreateHomeEx(in  s user_record,
                   in  a{sh} blobs,
                   in  t flags);
      RealizeHome(in  s user_name,
                  in  s secret);
      RemoveHome(in  s user_name);
      @org.freedesktop.systemd1.Privileged("true")
      FixateHome(in  s user_name,
                 in  s secret);
      AuthenticateHome(in  s user_name,
                       in  s secret);
      UpdateHome(in  s user_record);
      UpdateHomeEx(in  s user_record,
                   in  a{sh} blobs,
                   in  t flags);
      ResizeHome(in  s user_name,
                 in  t size,
                 in  s secret);
      ChangePasswordHome(in  s user_name,
                         in  s new_secret,
                         in  s old_secret);
      @org.freedesktop.systemd1.Privileged("true")
      LockHome(in  s user_name);
      @org.freedesktop.systemd1.Privileged("true")
      UnlockHome(in  s user_name,
                 in  s secret);
      AcquireHome(in  s user_name,
                  in  s secret,
                  in  b please_suspend,
                  out h send_fd);
      @org.freedesktop.systemd1.Privileged("true")
      RefHome(in  s user_name,
              in  b please_suspend,
              out h send_fd);
      @org.freedesktop.systemd1.Privileged("true")
      RefHomeUnrestricted(in  s user_name,
                          in  b please_suspend,
                          out h send_fd);
      @org.freedesktop.systemd1.Privileged("true")
      ReleaseHome(in  s user_name);
      ListSigningKeys(out a(sst) keys);
      GetSigningKey(in  s name,
                    out s der,
                    out t flags);
      AddSigningKey(in  s name,
                    in  s pem,
                    in  t flags);
      RemoveSigningKey(in  s name,
                       in  t flags);
      @org.freedesktop.systemd1.Privileged("true")
      LockAllHomes();
      @org.freedesktop.systemd1.Privileged("true")
      DeactivateAllHomes();
      @org.freedesktop.systemd1.Privileged("true")
      Rebalance();
    properties:
      readonly a(sso) AutoLogin = [...];
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
};

متدها (Methods)

GetHomeByName() در صورت ارائهٔ نام کاربری، اطلاعات پایه‌ای کاربر (یک زیرمجموعه حداقلی از رکورد کامل کاربر) را بازمی‌گرداند. اطلاعات ارائه‌شده کم‌وبیش با آنچه getpwnam(3) بازمی‌گرداند مطابقت دارد: شناسه‌های عددی UID و GID، نام واقعی، دایرکتوری خانگی و پوسته (shell). علاوه بر این، یک شناسه وضعیت که بیانگر وضعیتی است که دایرکتوری خانگی کاربر در آن قرار دارد، و همچنین یک مسیر گذرگاه که به شیء گذرگاه دربردارندهٔ رکورد کاربر و دایرکتوری خانگی اشاره دارد را بازمی‌گرداند. این شیء رابط org.freedesktop.home1.Home را پیاده‌سازی می‌کند که در ادامه مستند شده است. این متد، و بیشتر متدهای دیگر در این رابط که نام‌های کاربری را می‌گیرند، در صورتی که نام کاربری مشخص‌شده یک رشتهٔ خالی باشد، تلاش خواهند کرد از محدودهٔ خانگی خودِ فراخواننده استفاده کنند.

GetHomeByUID() مشابه GetHomeByName() است، اما اطلاعات را بر اساس شناسه عددی UID کاربر به دست می‌آورد.

GetUserRecordByName() نیز مشابه GetHomeByName() است، اما به جای رکوردهای تجزیه‌شده، داده‌های کامل رکورد کاربر در قالب JSON را بازمی‌گرداند. یک مقدار بولیِ اضافیِ بازگردانده‌شده مشخص می‌کند که آیا رکورد کامل است یا خیر. یک رکورد زمانی کامل در نظر گرفته می‌شود که بخش "privileged" (دارای دسترسی ویژه) در آن گنجانده شده باشد، و اگر حذف شده باشد ناقص در نظر گرفته می‌شود (برای جزئیات درباره بخش‌های مختلف رکورد کاربر به رکوردهای کاربری JSON[1] مراجعه کنید). به‌طور کلی، تنها کلاینت‌های مجاز و دارای دسترسی ویژه و کلاینت‌هایی که با هویت خودِ کاربر اجرا می‌شوند به بخش "privileged" دسترسی پیدا می‌کنند و بنابراین رکوردهای کامل را خواهند دید.

GetUserRecordByUID() مشابه GetUserRecordByName() است، اما رکورد کاربر منطبق با شناسه عددی UID مشخص‌شده را بازمی‌گرداند.

ListHomes() آرایه‌ای از تمام کاربران مدیریت‌شده به‌صورت محلی را بازمی‌گرداند. این آرایه شامل همان فیلدهایی است که GetHomeByName() بازمی‌گرداند: نام کاربری، UID عددی، وضعیت، GID عددی، نام واقعی، دایرکتوری خانگی، پوسته و مسیر گذرگاهِ شیءِ گذرگاهِ منطبق.

ActivateHome() دایرکتوری خانگی کاربر مشخص‌شده را فعال (یعنی سوار / mount) می‌کند. آرگومان دوم باید حاوی یک رکورد کاربر باشد که تنها از یک بخش "secret" (محرمانه) تشکیل شده است (تمام بخش‌های دیگر باید حذف شوند، برای جزئیات به رکوردهای کاربری JSON[1] مراجعه کنید)، و فقط باید شامل اعتبارنامه‌های محرمانه لازم برای باز کردن قفل دایرکتوری خانگی باشد. معمولاً یک کلاینت ابتدا این تابع را با یک رکورد کاملاً خالی فراخوانی می‌کند (که در صورت پیکربندی احراز هویت تک‌عاملی با یک توکن امنیتی متصل‌شده، احتمالاً کافی است)، و سپس بسته به کد خطای بازگردانده‌شده، در صورتی که اعتبارنامه‌های بیشتری لازم باشد، با رکوردی پرشده از اطلاعات بیشتر دوباره تلاش می‌کند. این تابع همگام (synchronous) است و تنها پس از اینکه دایرکتوری خانگی به‌طور کامل فعال شد (یا عملیات با شکست مواجه شد) بازمی‌گردد، که ممکن است مدتی طول بکشد. کلاینت‌ها باید برای این موضوع آماده باشند، و معمولاً باید مهلت زمانی فراخوانی متد D-Bus را متناسب با آن افزایش دهند. این متد معادل متد Activate() در رابط org.freedesktop.home1.Home است که در ادامه مستند شده است، اما می‌تواند روی شیء manager فراخوانی شود و در عوض نام کاربری را به عنوان یک آرگومان اضافی می‌گیرد.

ActivateHomeIfReferenced() همانند ActivateHome() است. با این حال، فراخوانی تنها زمانی موفق می‌شود که دایرکتوری خانگی در حال حاضر دارای ارجاع باشد. این متد در ترکیب با RefHomeUnrestricted() مفید است، که امکان ایجاد ارجاع به یک دایرکتوری خانگی را حتی در صورت فعال نبودن آن فراهم می‌کند.

DeactivateHome() دایرکتوری خانگی کاربر مشخص‌شده را غیرفعال (یعنی پیاده / unmount) می‌کند. این متد معادل متد Deactivate() در رابط org.freedesktop.home1.Home است که در ادامه مستند شده است.

RegisterHome() یک دایرکتوری خانگی جدید را به‌صورت محلی ثبت می‌کند. این متد رکورد کاربر JSON را به عنوان تنها آرگومان دریافت می‌کند (که معمولاً فاقد بخش "secret" است). ثبت یک دایرکتوری خانگی صرفاً رکورد کاربر را به سیستم می‌شناساند و دایرکتوری خانگی یا موارد مشابه را ایجاد نمی‌کند (انتظار می‌رود دایرکتوری از قبل وجود داشته باشد، یا بعداً ایجاد شود). این عملیات برای ثبت محلی دایرکتوری‌های خانگی‌ای مفید است که در جایی قرار ندارند که systemd-homed.service آن‌ها را به‌طور خودکار پیدا کند.

AdoptHome() نیز یک دایرکتوری خانگی جدید را به‌صورت محلی ثبت (پذیرش / adopt) می‌کند. این متد مسیری به خودِ دایرکتوری خانگی را می‌گیرد و آن را به‌صورت محلی ثبت خواهد کرد. این عمل فقط برای دایرکتوری‌های خانگی *.home و *.homedir/ کار می‌کند. این عملیات به‌طور خودکار برای تمام چنین محدوده‌های خانگی که در /home/ ظاهر می‌شوند انجام می‌شود، اما ممکن است با این فراخوانی برای دایرکتوری‌های موجود در جاهای دیگر به‌طور صریح درخواست شود. پارامتر flags در حال حاضر باید روی صفر تنظیم شود.

UnregisterHome() ثبت یک دایرکتوری خانگی موجود را لغو می‌کند. این متد یک نام کاربری را به عنوان آرگومان می‌گیرد و آنچه را که RegisterHome() انجام می‌دهد لغو می‌کند. این متد تلاشی برای حذف خود دایرکتوری خانگی نمی‌کند، بلکه صرفاً ثبت آن را در سیستم محلی لغو می‌نماید. توجه داشته باشید که اگر دایرکتوری خانگی در جایی قرار داشته باشد که systemd-homed.service در هر صورت به دنبال دایرکتوری‌های خانگی می‌گردد، این فراخوانی تنها تثبیت (fixation، پایین‌تر را ببینید) را لغو می‌کند، اما رکورد همچنان برای systemd-homed.service شناخته‌شده باقی می‌ماند و در میان رکوردهای شناخته‌شده فهرست می‌شود. از آنجا که رکورد کاربر درون دایرکتوری خانگی جاسازی شده است، این عملیات معمولاً داده‌های متعلق به کاربر یا رکورد او را از بین نمی‌برد. این متد معادل Unregister() در رابط org.freedesktop.home1.Home است.

CreateHome() یک دایرکتوری خانگی جدید را ثبت و ایجاد می‌کند. این متد یک رکورد کاربر JSON با تمام جزئیات مشخص‌شده را به عنوان آرگومان دریافت می‌کند (شامل بخش "secret"). این کار رکورد کاربر را به‌صورت محلی ثبت می‌کند و بسته به تنظیمات مشخص‌شده در رکورد در ترکیب با پیکربندی محلی، یک دایرکتوری خانگی منطبق با آن ایجاد می‌نماید.

CreateHomeEx() مشابه CreateHome() است، اما امکان ایجاد دایرکتوری خانگی همراه با یک دایرکتوری blob از پیش پرشده را فراهم می‌کند (برای اطلاعات بیشتر به دایرکتوری‌های حباب (Blob) رکورد کاربر[2] مراجعه کنید). این کار می‌تواند از طریق فرهنگ‌لغت (dictionary) پاس‌داده‌شده به عنوان آرگومان blobs به این متد انجام شود: مقادیر، توصیف‌کننده‌های پروندهٔ باز به فایل‌های معمولی هستند، و کلیدها نام فایل‌هایی هستند که باید حاوی داده‌های فایل مربوطه‌شان در دایرکتوری blob باشند. توجه داشته باشید که به دلایل امنیتی، توصیف‌کننده‌های پروندهٔ پاس‌داده‌شده به این متد باید دسترسی‌های کافی برای خواندن فایل هدف خود را داشته باشند و بنابراین نمی‌توانند "O_PATH" باشند؛ این کار برای اطمینان از این است که فراخواننده واقعاً مجاز به خواندن فایلی باشد که درخواست انتشار آن را در دایرکتوری‌های blob دارد. اگر رکورد کاربرِ پاس‌داده‌شده به عنوان اولین آرگومان حاوی فیلد "blobManifest" باشد، همان اعمال خواهد شد؛ در غیر این صورت، فیلد "blobManifest" تولید شده و در رکورد درج می‌شود. آرگومان flags ممکن است برای توسعه‌های آتی استفاده شود، اما در حال حاضر مقدار 0 را ارسال کنید.

RealizeHome() دایرکتوری خانگی‌ای را ایجاد (تحقق / realize) می‌کند که رکورد کاربر آن از قبل به‌صورت محلی ثبت شده است. این متد یک نام کاربری به همراه یک رکورد کاربر که تنها از بخش "secret" تشکیل شده است را دریافت می‌کند. فراخوانی RegisterHome() و به دنبال آن RealizeHome() عمدتاً معادل فراخوانی CreateHome() است، به جز اینکه دومی این دو کار را به روشی اتمیک (یکپارچه) با هم ترکیب می‌کند. این متد معادل Realize() در رابط org.freedesktop.home1.Home است.

RemoveHome() ثبت محلی یک رکورد کاربر را لغو می‌کند، و در صورت در دسترس بودن، دایرکتوری خانگی متعلق به آن را حذف می‌نماید. این متد یک نام کاربری را به عنوان آرگومان دریافت می‌کند. این متد معادل Remove() در رابط org.freedesktop.home1.Home است.

FixateHome() یک دایرکتوری خانگیِ به‌طور خودکار شناسایی‌شده را «تثبیت» (fixate) می‌کند. سرویس systemd-homed.service دایرکتوری‌های خانگی که اضافه یا متصل شده‌اند را به‌طور خودکار شناسایی کرده و به فهرست زمان اجرای رکوردهای کاربری که مدیریت می‌کند می‌افزاید. یک رکورد کاربر که به این شیوه کشف شده است می‌تواند «تثبیت» شود، که در این صورت از دایرکتوری خانگی به حافظه پایدار کپی می‌شود تا تخصیص UID/GID رکورد تثبیت گردد، و داده‌های تکمیلی رکورد کاربر (که معمولاً قبلاً رمزگذاری شده بودند) از دایرکتوری خانگی استخراج شوند. یک دایرکتوری خانگی باید پیش از امکان ورود به آن تثبیت شود. این فراخوانی متد، یک نام کاربری و یک رکورد کاربر JSON که تنها از بخش "secret" تشکیل شده را به عنوان آرگومان می‌گیرد. این متد معادل Fixate() در رابط org.freedesktop.home1.Home است.

AuthenticateHome() گذرواژه‌ها یا سایر اعتبارنامه‌های احراز هویتِ مرتبط با دایرکتوری خانگی را بررسی می‌کند. این متد یک نام کاربری و یک رکورد کاربر JSON که تنها شامل بخش "secret" است را به عنوان آرگومان می‌گیرد. توجه داشته باشید که بسیاری از فراخوانی‌های متدهای دیگر، ابتدا کاربر را احراز هویت می‌کنند تا عملیات دیگری را اجرا نمایند. این فراخوانی متد فقط احراز هویت می‌کند و هیچ عملیات دیگری را انجام نمی‌دهد. همانند ActivateHome() این متد معمولاً ابتدا با یک رکورد کاربر JSON خالی فراخوانی می‌شود، و سپس برای تلاش‌های بعدی با داده‌های احراز هویت تکمیلی ارائه‌شده پر می‌گردد. این متد معادل Authenticate() در رابط org.freedesktop.home1.Home است.

UpdateHome() یک رکورد کاربرِ ثبت‌شدهٔ محلی را به‌روزرسانی می‌کند. یک رکورد کاربر JSON با تمام جزئیات مشخص‌شده را به عنوان آرگومان می‌گیرد (که احتمالاً شامل بخش "secret" نیز هست). کاربری با نام و قلمرو (realm) منطبق باید از قبل به‌صورت محلی ثبت شده باشد، و برچسب زمانِ آخرین تغییرِ رکورد جدید باید تازه‌تر از رکورد کاربر موجود قبلی باشد. توجه داشته باشید که این عملیات فقط رکورد کاربر را به‌روزرسانی می‌کند، و گذرواژه‌ها/توکن‌های احراز هویت را از رکورد کاربر به پسانهٔ ذخیره‌سازی (storage back-end) انتقال نمی‌دهد، یا اندازه پسانهٔ ذخیره‌سازی را تغییر نمی‌دهد. معمولاً یک دایرکتوری خانگی ابتدا به‌روزرسانی می‌شود، و سپس گذرواژهٔ فضای ذخیره‌سازی زیرین با استفاده از ChangePasswordHome() به‌روز شده و همچنین اندازه فضای ذخیره‌سازی با استفاده از ResizeHome() تغییر داده می‌شود. این متد معادل Update() در رابط org.freedesktop.home1.Home است.

UpdateHomeEx() مشابه UpdateHome() است، اما امکان ایجاد تغییرات در دایرکتوری blob را فراهم می‌کند (برای اطلاعات بیشتر به دایرکتوری‌های حباب (Blob) رکورد کاربر[2] مراجعه کنید). آرگومان blobs به همان شیوهٔ CreateHomeEx() کار می‌کند، بنابراین برای جزئیات به آن بخش مراجعه کنید. محتوای جدید دایرکتوری blob که به این متد پاس داده می‌شود، به‌طور کامل جایگزین دایرکتوری blob موجود کاربر خواهد شد. آرگومان flags می‌تواند برای سفارشی‌سازی بیشتر رفتار این متد از طریق فلگ‌های تعریف‌شده به شرح زیر استفاده شود:

#define SD_HOMED_UPDATE_OFFLINE (UINT64_C(1) << 0)

هنگامی که SD_HOMED_UPDATE_OFFLINE (0x01) تنظیم شده باشد، هیچ تلاشی برای به‌روزرسانی نسخه‌های رکورد کاربر و دایرکتوری blob که درون دایرکتوری خانگی جاسازی شده‌اند انجام نمی‌شود. با این حال، تغییرات ذخیره می‌شوند و ممکن است دفعه بعد که دایرکتوری خانگی تطبیق داده می‌شود (به احتمال زیاد هنگام ورود بعدی کاربر) در دایرکتوری خانگی منتشر شوند. توجه داشته باشید که هر تغییری که با تنظیم این فلگ ایجاد شود ممکن است از بین برود اگر محدودهٔ خانگی رکورد جدیدتری داشته باشد، که این اتفاق در صورتی رخ می‌دهد که محدودهٔ خانگی پس از این فراخوانی متد روی ماشین دیگری به‌روزرسانی شود. این متد معادل UpdateEx() در رابط org.freedesktop.home1.Home است.

ResizeHome() اندازه فضای ذخیره‌سازی مرتبط با یک رکورد کاربر را تغییر می‌دهد. نام کاربری، اندازه دیسک به بایت، و به‌صورت اختیاری یک رکورد کاربر که تنها از بخش "secret" تشکیل شده است را به عنوان آرگومان دریافت می‌کند. اگر اندازه به صورت UINT64_MAX مشخص شود، اندازه فضای ذخیره‌سازی به همان اندازه‌ای که قبلاً در رکورد کاربر مشخص شده تغییر می‌یابد. معمولاً اگر رکورد کاربر با استفاده از UpdateHome() در بالا به‌روزرسانی شود، از این متد برای انتقال اندازه پیکربندی‌شده در آن به پسانهٔ ذخیره‌سازی زیرین استفاده می‌شود. این متد معادل Resize() در رابط org.freedesktop.home1.Home است.

ChangePasswordHome() گذرواژه‌ها/توکن‌های احراز هویت یک دایرکتوری خانگی را تغییر می‌دهد. یک نام کاربری، و دو شیء رکورد کاربر JSON که هر کدام تنها از بخش "secret" تشکیل شده‌اند را برای گذرواژه‌ها/توکن‌های احراز هویت قدیمی و جدید می‌گیرد. اگر رکورد کاربرِ حاوی داده‌های گذرواژه/توکن جدید به‌صورت خالی مشخص شود، تنظیمات رکورد کاربر موجود به فضای ذخیره‌سازی دایرکتوری خانگی منتقل می‌شود. این معمولاً پس از آنکه یک رکورد کاربر با استفاده از UpdateHome() به‌روز شد، به منظور انتقال اسرار/توکن‌های احراز هویت به حافظه ذخیره‌سازی استفاده می‌شود. پیش‌زمینه: بسته به پسانه (backend)، اعتبارنامه‌های احراز هویت کاربر در چندین مکان ذخیره می‌شوند: رکورد کاربرِ نگهداری‌شده روی میزبان (host)، رکورد کاربر نگهداری‌شده در دایرکتوری خانگی و اسلات حجم رمزگذاری‌شدهٔ LUKS. اگر از دایرکتوری خانگی موقتاً روی ماشین دیگری استفاده شود، و گذرواژه در آنجا تغییر یابد، و سپس به میزبان اصلی بازگردانده شود، ممکن است گذرواژه‌های این سه مکان ناهماهنگ شوند. با صدور فراخوانی ChangePasswordHome() این سه مکان به‌روزرسانی می‌شوند تا با جدیدترین اطلاعات مطابقت داشته باشند. این متد معادل ChangePassword() در رابط org.freedesktop.home1.Home است.

LockHome() دسترسی به یک دایرکتوری خانگی را موقتاً معلق می‌کند و هرگونه کلید رمزنگاری را از حافظه پاک (flush) می‌نماید. این قابلیت تنها در برخی پسانه‌ها پشتیبانی می‌شود و معمولاً در هنگام تعلیق (suspend) سیستم انجام می‌شود تا در زمان خواب سیستم، دایرکتوری‌های خانگی به شکلی موثر ایمن شوند. نام کاربری را به عنوان تنها آرگومان می‌گیرد. اگر برنامه‌ای در زمان قفل بودن دایرکتوری خانگی تلاش کند به آن دسترسی پیدا کند، معمولاً تا زمانی که قفل دایرکتوری خانگی دوباره باز شود متوقف (freeze) خواهد شد. این متد معادل Lock() در رابط org.freedesktop.home1.Home است.

UnlockHome() اثر LockHome() را خنثی می‌کند. یک نام کاربری و یک رکورد کاربر که تنها از بخش "secret" تشکیل شده است را به عنوان آرگومان دریافت می‌کند. این متد معادل Unlock() در رابط org.freedesktop.home1.Home است.

AcquireHome() یک دایرکتوری خانگی را در حالت شمارش ارجاع (reference counted) فعال یا قفل‌گشایی می‌کند. یک نام کاربری و یک رکورد کاربر که تنها شامل بخش "secret" است را به عنوان آرگومان می‌گیرد. اگر دایرکتوری خانگی هنوز فعال نباشد، فعال می‌شود. اگر در حال حاضر قفل باشد، قفل آن باز می‌شود. پس از اتمام، یک ارجاع به فعال‌سازی/قفل‌گشایی دایرکتوری خانگی از طریق یک توصیف‌کنندهٔ پرونده (file descriptor) بازگردانده می‌شود. هنگامی که آخرین کلاینتی که چنین توصیف‌کننده پرونده‌ای را به دست آورده بود آن را ببندد، دایرکتوری خانگی به‌طور خودکار دوباره غیرفعال می‌شود. این متد معمولاً هنگام ورود (login) کاربر فراخوانی می‌شود، و توصیف‌کننده پرونده تا زمان خروج (logout) مجدد کاربر نگه داشته می‌شود، بنابراین تضمین می‌کند که دایرکتوری خانگی کاربر هنگام خروج او می‌تواند دوباره به شکلی مطمئن و پایدار پیاده (unmount) شود. آرگومان سوم مقداری بولی است که نشان می‌دهد آیا کلاینت فراخواننده قادر است هنگام بازگشت سیستم از حالت تعلیق (suspend) به‌طور خودکار مجدداً احراز هویت کند یا خیر. این مقدار باید توسط تمام کلاینت‌هایی تنظیم شود که یک صفحه قفل امن را خارج از بستر (context) کاربر پیاده‌سازی می‌کنند؛ صفحه‌ای که با بازگشت سیستم از تعلیق بالا می‌آید و می‌تواند برای به دست آوردن مجدد اعتبارنامه‌ها جهت باز کردن قفل دایرکتوری خانگی کاربر استفاده شود. اگر یک دایرکتوری خانگی حداقل یک کلاینت با ارجاع باز داشته باشد که از این قابلیت پشتیبانی نمی‌کند، در هنگام تعلیق سیستم به‌طور خودکار معلق نخواهد شد، در غیر این صورت معلق می‌شود. این متد معادل Acquire() در رابط org.freedesktop.home1.Home است.

RefHome() مشابه AcquireHome() است اما هیچ رکورد کاربری با بخش "secret" نمی‌گیرد، یعنی بدون آنکه خود تلاش کند دایرکتوری خانگی را فعال/قفل‌گشایی کند، یک ارجاع اضافی به دایرکتوری خانگیِ از قبل فعال‌شده/قفل‌گشایی‌شده می‌گیرد. اگر دایرکتوری خانگی از قبل فعال نشده باشد، با شکست مواجه می‌شود. این متد معادل Ref() در رابط org.freedesktop.home1.Home است.

RefHomeUnrestricted() همانند RefHome() است اما حتی در صورتی که محدودهٔ خانگی در حال حاضر فعال نباشد نیز موفق می‌شود. این متد در ترکیب با ActivateHomeIfReferenced() مفید است.

ReleaseHome() در صورتی که تمام توصیف‌کننده‌های پروندهٔ ارجاع‌دهنده به دایرکتوری خانگی که از طریق AcquireHome() یا RefHome() به دست آمده بودند قبلاً بسته شده باشند، دایرکتوری خانگی را دوباره آزاد می‌کند. توجه داشته باشید که این فراخوانی در واقع باعث غیرفعال شدن دایرکتوری خانگی نمی‌شود (که این امر به‌طور خودکار هنگام بسته شدن آخرین توصیف‌کننده پروندهٔ ارجاع‌دهنده رخ می‌دهد)، بلکه صرفاً یک سازوکار همگام‌سازی است که اجازه می‌دهد خاتمهٔ نشست (session) کاربر تا زمانی که هرگونه غیرفعال‌سازیِ آغازشده تکمیل شود، به تعویق بیفتد. این متد معادل Release() در رابط org.freedesktop.home1.Home است.

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

DeactivateAllHomes() تمام محدوده‌های خانگی را که در حال حاضر فعال هستند غیرفعال می‌کند. این متد معمولاً اندکی پیش از خاموش شدن سیستم به‌طور خودکار فراخوانی می‌شود.

Rebalance() فضای آزاد دیسک را به‌صورت همگام میان محدوده‌های خانگی بازتوزیع و متعادل‌سازی (rebalance) می‌کند. این متد تنها در صورتی عملیاتی را اجرا می‌کند که حداقل یک محدودهٔ خانگی با استفاده از پسانهٔ LUKS2 فعال باشد و قابلیت بازتوزیع آن فعال باشد، و در غیر این صورت یک عملیات بی‌اثر (NOP) است.

ListSigningKeys() فهرستی از کلیدهای امضای نصب‌شدهٔ محدودهٔ خانگی را به دست می‌آورد. آرایه‌ای از نام‌های کلید به همراه داده‌های کلید عمومیِ کُدگذاری‌شده با فرمت PEM را بازمی‌گرداند. هر مدخل همچنین دارای یک مقدار فلگ است که در حال حاضر استفاده نمی‌شود و کلاینت‌ها باید آن را نادیده بگیرند.

GetSigningKey() بخش عمومی کُدگذاری‌شده با PEM از کلید امضای محدودهٔ خانگیِ مشخص‌شده با نام تعیین‌شده را به دست می‌آورد. همچنین یک مقدار فلگِ در حال حاضر استفاده‌نشده بازمی‌گرداند که باید نادیده گرفته شود. پارامتر flags در حال حاضر باید روی صفر تنظیم شود.

AddSigningKey() یک کلید جدید به فهرست کلیدهای امضای محدودهٔ خانگی می‌افزاید. یک رشتهٔ نام (آزاد، مناسب به عنوان نام فایل، با پسوند ".public")، داده‌های کلید عمومیِ کُدگذاری‌شده با PEM و یک مقدار فلگِ در حال حاضر استفاده‌نشده که باید صفر باشد را دریافت می‌کند. پارامتر flags در حال حاضر باید روی صفر تنظیم شود.

RemoveSigningKey() یک کلید را از فهرست کلیدهای امضای محدودهٔ خانگی حذف می‌کند. نام کلید برای حذف و یک مقدار فلگِ در حال حاضر استفاده‌نشده که باید صفر باشد را دریافت می‌کند. پارامتر flags در حال حاضر باید روی صفر تنظیم شود.

ویژگی‌ها (Properties)

AutoLogin آرایه‌ای از ساختارها شامل نام کاربری، نام جایگاه (seat name) و مسیر شیء یک شیء دایرکتوری خانگی را ارائه می‌دهد. تمام کاربران مدیریت‌شده به‌صورت محلی که فیلد "autoLogin" در آن‌ها تنظیم شده است، همراه با نام جایگاهی که با آن مرتبط هستند در اینجا فهرست می‌شوند. یک مدیر نمایش (display manager) می‌تواند این ویژگی را نظارت کند و صفحه ورود به سیستم را با کاربرانی که از این طریق ارائه شده‌اند از قبل پر نماید.

شیء HOME (THE HOME OBJECT)

node /org/freedesktop/home1/home {
  interface org.freedesktop.home1.Home {
    methods:
      Activate(in  s secret);
      ActivateIfReferenced(in  s secret);
      @org.freedesktop.systemd1.Privileged("true")
      Deactivate();
      Unregister();
      Realize(in  s secret);
      Remove();
      @org.freedesktop.systemd1.Privileged("true")
      Fixate(in  s secret);
      Authenticate(in  s secret);
      Update(in  s user_record);
      UpdateEx(in  s user_record,
               in  a{sh} blobs,
               in  t flags);
      Resize(in  t size,
             in  s secret);
      ChangePassword(in  s new_secret,
                     in  s old_secret);
      @org.freedesktop.systemd1.Privileged("true")
      Lock();
      @org.freedesktop.systemd1.Privileged("true")
      Unlock(in  s secret);
      @org.freedesktop.systemd1.Privileged("true")
      Acquire(in  s secret,
              in  b please_suspend,
              out h send_fd);
      @org.freedesktop.systemd1.Privileged("true")
      Ref(in  b please_suspend,
          out h send_fd);
      @org.freedesktop.systemd1.Privileged("true")
      RefUnrestricted(in  b please_suspend,
                      out h send_fd);
      @org.freedesktop.systemd1.Privileged("true")
      Release();
    properties:
      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
      readonly s UserName = '...';
      readonly u UID = ...;
      readonly (suusss) UnixRecord = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly s State = '...';
      @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates")
      readonly (sb) UserRecord = ...;
  };
  interface org.freedesktop.DBus.Peer { ... };
  interface org.freedesktop.DBus.Introspectable { ... };
  interface org.freedesktop.DBus.Properties { ... };
  interface org.freedesktop.DBus.ObjectManager { ... };
};

متدها (Methods)

Activate()، ActivateIfReferenced()، Deactivate()، Unregister()، Realize()، Remove()، Fixate()، Authenticate()، Update()، UpdateEx()، Resize()، ChangePassword()، Lock()، Unlock()، Acquire()، Ref()، RefUnrestricted()، و Release() همانند همتاهای متناظر خود در رابط org.freedesktop.home1.Manager عمل می‌کنند (بالا را ببینید). تفاوت اصلی این است که آن‌ها متدهای اشیاء دایرکتوری خانگی هستند، و در نتیجه هیچ پارامتر نام کاربری اضافی حمل نمی‌کنند. اینکه کدام‌یک از دو شیوهٔ متدها فراخوانی شود بستگی به دستگیره‌های (handles) شناخته‌شده از کاربر در سمت کلاینت دارد: اگر تنها نام کاربری مشخص باشد، ترجیح بر استفاده از متدهای روی شیء manager است چرا که آنها فقط با نام‌های کاربری کار می‌کنند. کلاینت‌ها همچنین می‌توانند به سادگی با استفاده از متدهای روی شیء manager همراه با یک رشته خالی به عنوان نام کاربری، روی محدودهٔ خانگی خود عمل کنند. با این حال، اگر کلاینت مسیر شیء دایرکتوری خانگی را قبلاً به شکلی به دست آورده باشد، ترجیح بر این است که در عوض روی اشیاء org.freedesktop.home1.Home عمل نماید.