.\" $OpenBSD: ssh-agent.1,v 1.87 2026/05/27 03:04:30 djm Exp $ .\" .\" Author: Tatu Ylonen .\" Copyright (c) 1995 Tatu Ylonen , Espoo, Finland .\" All rights reserved .\" .\" As far as I am concerned, the code I have written for this software .\" can be used freely for any purpose. Any derived versions of this .\" software must be clearly marked as such, and if the derived work is .\" incompatible with the protocol description in the RFC file, it must be .\" called by a name other than "ssh" or "Secure Shell". .\" .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. .\" Copyright (c) 1999 Aaron Campbell. All rights reserved. .\" Copyright (c) 1999 Theo de Raadt. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd $Mdocdate: May 27 2026 $ .Dt SSH-AGENT 1 .Os .Sh "نام (NAME)" .Nm ssh-agent .Nd کارگزار احراز هویت OpenSSH .Sh "خلاصه دستور (SYNOPSIS)" .Nm ssh-agent .Op Fl c | s .Op Fl \&DdTU .Op Fl a Ar bind_address .Op Fl E Ar fingerprint_hash .Op Fl O Ar option .Op Fl P Ar allowed_providers .Op Fl t Ar life .Nm ssh-agent .Op Fl TU .Op Fl a Ar bind_address .Op Fl E Ar fingerprint_hash .Op Fl O Ar option .Op Fl P Ar allowed_providers .Op Fl t Ar life .Ar command Op Ar arg ... .Nm ssh-agent .Op Fl c | s .Fl k .Nm ssh-agent .Fl u .Nm ssh-agent .Fl V .Sh "توضیحات (DESCRIPTION)" .Nm برنامه‌ای برای نگهداری کلیدهای خصوصی مورد استفاده در احراز هویت با کلید عمومی است. از طریق استفاده از متغیرهای محیطی، کارگزار می‌تواند مکان‌یابی شده و هنگام ورود به ماشین‌های دیگر با استفاده از .Xr ssh 1 به‌طور خودکار برای احراز هویت به کار گرفته شود. .Pp گزینه‌ها به شرح زیر هستند: .Bl -tag -width Ds .It Fl a Ar bind_address متصل کردن کارگزار به سوکت دامنهٔ .Ux در نشانی .Ar bind_address . حالت پیش‌فرض، ایجاد یک سوکت در مسیری تصادفی منطبق بر .Pa $HOME/.ssh/agent/s.* است. .It Fl c تولید دستورهای C-shell در خروجی استاندارد. اگر متغیر .Ev SHELL شبیه به پوسته‌ای از نوع csh باشد، این حالت پیش‌فرض است. .It Fl D حالت پیش‌زمینه. هنگامی که این گزینه مشخص شود، .Nm منشعب (fork) نخواهد شد. .It Fl d حالت اشکال‌زدایی. هنگامی که این گزینه مشخص شود، .Nm منشعب (fork) نخواهد شد و اطلاعات اشکال‌زدایی را در خروجی استاندارد خطا می‌نویسد. .It Fl E Ar fingerprint_hash الگوریتم درهم‌سازی (هش) مورد استفاده هنگام نمایش اثر انگشت کلید را مشخص می‌کند. گزینه‌های معتبر عبارتند از: .Dq md5 و .Dq sha256 . مقدار پیش‌فرض .Dq sha256 است. .It Fl k متوقف کردن (kill) کارگزار فعلی (که توسط متغیر محیطی .Ev SSH_AGENT_PID مشخص شده است). .It Fl O Ar option تعیین یک گزینه هنگام راه‌اندازی .Nm . گزینه‌های پشتیبانی‌شده عبارتند از: .Cm allow-remote-pkcs11 , .Cm no-restrict-websafe و .Cm websafe-allow . .Pp گزینهٔ .Cm allow-remote-pkcs11 به کلاینت‌های یک .Nm بازارسال‌شده (forwarded) اجازه می‌دهد کتابخانه‌های ارائه‌دهندهٔ PKCS#11 یا FIDO را بارگذاری کنند. به‌طور پیش‌فرض تنها کلاینت‌های محلی مجاز به انجام این عملیات هستند. توجه داشته باشید که اعلام راه دور (remote) بودن کلاینتِ .Nm توسط .Xr ssh 1 انجام می‌شود، و استفاده از سایر ابزارها برای بازارسال دسترسی به سوکت کارگزار ممکن است این محدودیت را دور بزند. .Pp گزینهٔ .Cm no-restrict-websafe به .Nm دستور می‌دهد تا امضاها با استفاده از کلیدهای FIDO را که ممکن است درخواست‌های احراز هویت وب باشند، مجاز بداند. به‌طور پیش‌فرض، .Nm درخواست‌های امضا برای کلیدهای FIDO را که در آن‌ها رشتهٔ کاربرد کلید با .Dq ssh: شروع نمی‌شود و داده‌هایی که قرار است امضا شوند شبیه به یک درخواست احراز هویت کاربر در .Xr ssh 1 یا امضای .Xr ssh-keygen 1 نیستند، رد می‌کند. رفتار پیش‌فرض از این امر جلوگیری می‌کند که دسترسی بازارسال‌شده به یک کلید FIDO، توانایی احراز هویت در وب‌سایت‌ها را نیز به‌طور ضمنی منتقل کند. .Pp به‌عنوان روشی جایگزین، گزینهٔ .Cm websafe-allow امکان تعیین یک فهرست الگو از رشته‌های کاربرد کلید را برای جایگزینی با فهرست مجاز پیش‌فرض برنامه‌ها فراهم می‌کند؛ برای نمونه: .Dq websafe-allow=ssh:*,example.org,*.example.com .Pp برای شرح نحو فهرست الگو، بخش PATTERNS را در .Xr ssh_config 5 ببینید. .It Fl P Ar allowed_providers یک فهرست الگو از مسیرهای قابل قبول برای کتابخانه‌های اشتراکی میان‌افزار احراز هویت‌کنندهٔ FIDO و ارائه‌دهندهٔ PKCS#11 را مشخص می‌کند که ممکن است با گزینه‌های .Fl S یا .Fl s در .Xr ssh-add 1 استفاده شوند. کتابخانه‌هایی که با این فهرست الگو مطابقت نداشته باشند، رد خواهند شد. فهرست پیش‌فرض .Dq /usr/lib*/*,/usr/local/lib*/* است. .Pp برای شرح نحو فهرست الگو، بخش PATTERNS را در .Xr ssh_config 5 ببینید. .It Fl s تولید دستورهای Bourne shell در خروجی استاندارد. اگر متغیر .Ev SHELL شبیه به پوسته‌ای از نوع csh نباشد، این حالت پیش‌فرض است. .It Fl T متصل کردن سوکت کارگزار درون یک زیردایرکتوری تصادفی به شکل .Pa $TMPDIR/ssh-XXXXXXXXXX/agent.\*(Ltppid\*(Gt ، به‌جای رفتار پیش‌فرض که استفاده از یک نام تصادفی منطبق بر .Pa $HOME/.ssh/agent/s.* است. .It Fl t Ar life تنظیم یک مقدار پیش‌فرض برای حداکثر طول عمر هویت‌های اضافه‌شده به کارگزار. طول عمر می‌تواند بر حسب ثانیه یا با قالبی زمانی طبق مشخصات ارائه‌شده در .Xr sshd_config 5 تعیین شود. طول عمر مشخص‌شده برای یک هویت با .Xr ssh-add 1 این مقدار را باطل می‌کند. بدون این گزینه، حداکثر طول عمر پیش‌فرض به‌صورت نامحدود (همیشگی) خواهد بود. .It Fl U به .Nm دستور می‌دهد که سوکت‌های قدیمی و بی‌استفادهٔ کارگزار را در .Pa $HOME/.ssh/agent/ پاک‌سازی نکند. .It Fl u به .Nm دستور می‌دهد که تنها سوکت‌های قدیمی و بی‌استفادهٔ کارگزار را در .Pa $HOME/.ssh/agent/ پاک‌سازی کرده و سپس بی‌درنگ خارج شود. اگر این گزینه دو بار داده شود، .Nm سوکت‌های قدیمی کارگزار را صرف‌نظر از نام میزبان ایجادکنندهٔ آن‌ها حذف خواهد کرد. .It Ar command Op Ar arg ... اگر یک دستور (و آرگومان‌های اختیاری) داده شود، به‌عنوان یک زیرفرآیند از کارگزار اجرا می‌شود. کارگزار با پایان یافتن دستوری که در خط فرمان داده شده، به‌طور خودکار خارج می‌شود. .It Fl V نمایش شماره نسخه و خروج. .El .Pp سه روش اصلی برای راه‌اندازی کارگزار وجود دارد. روش نخست در آغاز یک نشست گرافیکی X است، به‌طوری که تمام پنجره‌ها یا برنامه‌های دیگر به‌عنوان فرزندان برنامهٔ .Nm راه‌اندازی می‌شوند. کارگزار دستوری را آغاز می‌کند که متغیرهای محیطی‌اش تحت آن صادر می‌شوند؛ برای نمونه .Cm ssh-agent xterm & . با پایان یافتن دستور، کارگزار نیز پایان می‌یابد. .Pp روش دوم برای یک نشست ورود به سیستم به کار می‌رود. هنگامی که .Nm آغاز می‌شود، دستورهای پوسته‌ای را که برای تنظیم متغیرهای محیطی‌اش لازم است چاپ می‌کند؛ این دستورها به نوبهٔ خود می‌توانند در پوستهٔ فراخوان ارزیابی و اجرا شوند، برای نمونه .Cm eval `ssh-agent -s` . .Pp در هر دو مورد، .Xr ssh 1 این متغیرهای محیطی را بررسی می‌کند و از آن‌ها برای برقراری ارتباط با کارگزار بهره می‌برد. .Pp روش سوم برای اجرای .Nm از طریق فعال‌سازی سوکت (socket activation) توسط یک فرآیند ناظر مانند systemd است. در این حالت، فرآیند ناظر سوکت شنونده را ایجاد می‌کند و مسئول راه‌اندازی .Nm در صورت نیاز، و همچنین اطلاع‌رسانی مکان سوکت شنونده به سایر برنامه‌های نشست کاربر است. فعال‌سازی سوکت زمانی استفاده می‌شود که .Nm با هر یک از فلگ‌های .Fl d یا .Fl D آغاز شود، هیچ نشانی شنود سوکتی با فلگ .Fl a مشخص نشده باشد، و هر دو متغیر محیطی .Ev LISTEN_FDS و .Ev LISTEN_PID به‌درستی توسط فرآیند ناظر ارائه شده باشند. .Pp کارگزار در ابتدا فاقد هرگونه کلید خصوصی است. کلیدها با استفاده از .Xr ssh-add 1 یا توسط .Xr ssh 1 در صورت تنظیم .Cm AddKeysToAgent در .Xr ssh_config 5 اضافه می‌شوند. چندین هویت می‌توانند به‌طور هم‌زمان در .Nm ذخیره شوند و .Xr ssh 1 در صورت وجود، به‌طور خودکار از آن‌ها استفاده خواهد کرد. همچنین از .Xr ssh-add 1 برای حذف کلیدها از .Nm و استعلام کلیدهای نگهداری‌شده در آن استفاده می‌شود. .Pp اتصالات به .Nm می‌توانند با استفاده از گزینهٔ .Fl A در .Xr ssh 1 (اما هشدارهای مستندشده در آن را ملاحظه کنید) از سایر میزبان‌های راه دور بازارسال شوند، که نیاز به ذخیرهٔ داده‌های احراز هویت در ماشین‌های دیگر را از بین می‌برد. عبارت‌های عبور و کلیدهای خصوصی احراز هویت هرگز از شبکه عبور نمی‌کنند: اتصال به کارگزار از طریق اتصالات راه دور SSH بازارسال می‌شود و نتیجه به درخواست‌کننده بازگردانده می‌شود، که به کاربر امکان می‌دهد به شیوه‌ای امن در هر کجای شبکه به هویت‌های خود دسترسی داشته باشد. .Pp .Nm با دریافت سیگنال .Dv SIGUSR1 تمام کلیدهایی را که بارگذاری کرده است حذف خواهد کرد. .Sh "محیط (ENVIRONMENT)" .Bl -tag -width "SSH_AGENT_PID" .It Ev SSH_AGENT_PID هنگامی که .Nm آغاز می‌شود، شناسهٔ فرآیند (PID) کارگزار را در این متغیر ذخیره می‌کند. .It Ev SSH_AUTH_SOCK هنگامی که .Nm آغاز می‌شود، یک سوکت دامنهٔ .Ux ایجاد کرده و مسیر آن را در این متغیر ذخیره می‌کند. این سوکت تنها برای کاربر جاری قابل دسترسی است، اما به‌سادگی توسط ریشه (root) یا نمونهٔ دیگری از همان کاربر قابل سوءاستفاده است. .El .Sh "فایل‌ها (FILES)" .Bl -tag -width Ds .It Pa $HOME/.ssh/agent/s.* سوکت‌های دامنهٔ .Ux که برای برقراری ارتباط با کارگزار احراز هویت استفاده می‌شوند. این سوکت‌ها تنها باید توسط مالک قابل خواندن باشند. سوکت‌ها باید هنگام خروج کارگزار به‌طور خودکار حذف شوند. .El .Sh "همچنین ببینید (SEE ALSO)" .Xr ssh 1 , .Xr ssh-add 1 , .Xr ssh-keygen 1 , .Xr ssh_config 5 , .Xr sshd 8 .Sh "نویسندگان (AUTHORS)" .An -nosplit OpenSSH مشتقی از نگارش اصلی و آزاد ssh 1.2.12 است که توسط .An Tatu Ylonen منتشر شده بود. .An Aaron Campbell , Bob Beck , Markus Friedl , Niels Provos , Theo de Raadt و .An Dug Song اشکالات متعددی را برطرف کرده، امکانات جدیدتری افزودند و OpenSSH را پدید آوردند. .An Markus Friedl پشتیبانی از پروتکل SSH نسخه‌های 1.5 و 2.0 را اضافه کرد.