SSH-ADD(1) راهنمای دستورات کاربردی SSH-ADD(1)

ssh-add - افزودن هویتهای کلید خصوصی به کارگزار احراز هویت

ssh-add [-CcDdKkLlNqvXx] [-E fingerprint_hash] [-H hostkey_file] [-h destination_constraint] [-S provider] [-t life] [file ...]
ssh-add -s pkcs11 [-Cv] [certificate ...]
ssh-add -e pkcs11
ssh-add -T pubkey ...
ssh-add -Q

دستور ssh-add هویت‌های کلید خصوصی را به کارگزار احراز هویت، ssh-agent(1)، اضافه می‌کند. هنگامی که بدون آرگومان اجرا شود، فایل‌های ~/.ssh/id_rsa، ~/.ssh/id_ecdsa، ~/.ssh/id_ecdsa_sk، ~/.ssh/id_ed25519، ~/.ssh/id_ed25519_sk و ~/.ssh/id_mldsa44_ed25519 را اضافه می‌کند. پس از بارگذاری یک کلید خصوصی، ssh-add تلاش خواهد کرد تا اطلاعات گواهی مربوطه را از نام فایلی که با افزودن -cert.pub به انتهای نام فایل کلید خصوصی به دست می‌آید، بارگذاری کند. نام‌های فایل جایگزین را می‌توان در خط فرمان مشخص کرد.

اگر فایلی به عبارت عبور (passphrase) نیاز داشته باشد، ssh-add عبارت عبور را از کاربر درخواست می‌کند. عبارت عبور از پایانه (tty) کاربر خوانده می‌شود. اگر چند فایل هویت مشخص شده باشند، ssh-add آخرین عبارت عبور را مجدداً امتحان خواهد کرد.

کارگزار احراز هویت باید در حال اجرا باشد و متغیر محیطی SSH_AUTH_SOCK باید شامل نام سوکت آن باشد تا ssh-add بتواند کار کند.

گزینه‌ها به شرح زیر هستند:

هنگام بارگذاری کلیدها در کارگزار یا حذف کلیدها از آن، تنها گواهی‌ها را پردازش کرده و از کلیدهای ساده صرف‌نظر می‌کند.
مشخص می‌کند که هویت‌های اضافه‌شده باید پیش از استفاده برای احراز هویت، نیاز به تأیید داشته باشند. تأیید توسط ssh-askpass(1) انجام می‌شود. تأیید موفقیت‌آمیز به جای متنی که در درخواست‌کننده وارد شده باشد، با یک وضعیت خروج صفر از سوی ssh-askpass(1) مشخص می‌شود.
تمام هویت‌ها را از کارگزار حذف می‌کند.
به جای افزودن هویت‌ها، هویت‌ها را از کارگزار حذف می‌کند. اگر ssh-add بدون آرگومان اجرا شده باشد، کلیدهای مربوط به هویت‌های پیش‌فرض و گواهی‌های متناظر آن‌ها حذف خواهند شد. در غیر این صورت، فهرست آرگومان‌ها به عنوان فهرستی از مسیرهای فایل‌های کلید عمومی برای تعیین کلیدها و گواهی‌های قابل حذف از کارگزار تفسیر خواهد شد. اگر هیچ کلید عمومی در مسیر داده‌شده یافت نشود، ssh-add پسوند .pub را به انتهای آن افزوده و دوباره امتحان می‌کند. اگر فهرست آرگومان‌ها شامل - باشد، آنگاه ssh-add کلیدهای عمومیِ قابل حذف را از ورودی استاندارد می‌خواند.
الگوریتم درهم‌سازی (هش) مورد استفاده هنگام نمایش اثر انگشت (fingerprint) کلید را مشخص می‌کند. گزینه‌های معتبر عبارتند از: md5 و sha256. مقدار پیش‌فرض sha256 است.
کلیدهای ارائه‌شده توسط کتابخانه مشترک PKCS#11 به نام pkcs11 را حذف می‌کند.
یک فایل میزبان‌های شناخته‌شده (known hosts) را برای جستجوی کلیدهای میزبان هنگام استفاده از کلیدهای مقید به مقصد از طریق گزینهٔ -h مشخص می‌کند. این گزینه می‌تواند چندین بار مشخص شود تا امکان جستجو در چندین فایل فراهم گردد. اگر هیچ فایلی مشخص نشود، ssh-add از فایل‌های پیش‌فرض میزبان‌های شناخته‌شده در ssh_config(5) استفاده خواهد کرد: ~/.ssh/known_hosts، ~/.ssh/known_hosts2، /etc/ssh/ssh_known_hosts و /etc/ssh/ssh_known_hosts2.
هنگام افزودن کلیدها، آن‌ها را مقید می‌سازد تا تنها از طریق میزبان‌های خاص یا برای مقصدهای خاص قابل استفاده باشند.
محدودیت‌های مقصد به شکل [user@]dest-hostname استفاده از کلید را تنها از میزبان مبدا (میزبانی که ssh-agent(1) را اجرا می‌کند) به میزبان مقصد فهرست‌شده، به همراه نام کاربری اختیاری مجاز می‌سازد.
محدودیت‌های به شکل src-hostname>[user@]dst-hostname اجازه می‌دهند کلیدی که روی یک ssh-agent(1) هدایت‌شده (forwarded) موجود است، از طریق یک میزبان خاص (که با src-hostname مشخص شده) برای احراز هویت در میزبان دورتری که با dst-hostname مشخص گردیده، به کار رود.
هنگام بارگذاری کلیدها می‌توان چندین قید و محدودیت مقصد اضافه کرد. هنگام تلاش برای احراز هویت با کلیدی که دارای محدودیت‌های مقصد است، کل مسیر اتصال، از جمله هدایت ssh-agent(1)، در برابر آن قیدها بررسی می‌شود و هر پرش (hop) باید مجاز باشد تا تلاش برای احراز هویت موفق شود. برای مثال، اگر کلیدی به یک میزبان راه دور به نام host-b هدایت شود و در تلاش برای احراز هویت در میزبان دیگری به نام host-c باشد، عملیات تنها در صورتی موفقیت‌آمیز خواهد بود که host-b از میزبان مبدا مجاز شمرده شده باشد و پرش بعدی host-b>host-c نیز توسط محدودیت‌های مقصد مجاز باشد.
میزبان‌ها بر اساس کلیدهای میزبان خود شناسایی می‌شوند، و توسط ssh-add از فایل‌های میزبان‌های شناخته‌شده جستجو می‌گردند. می‌توان از الگوهای نویسه عام (wildcard) برای نام‌های میزبان استفاده کرد و کلیدهای میزبان مبتنی بر گواهی نیز پشتیبانی می‌شوند. به‌طور پیش‌فرض، کلیدهای اضافه‌شده توسط ssh-add دارای محدودیت مقصد نیستند.
محدودیت‌های مقصد در نگارش OpenSSH 8.9 اضافه شدند. هنگام استفاده از کلیدهای مقید به مقصد از طریق یک کانال هدایت‌شدهٔ ssh-agent(1)، پشتیبانی در هر دو کلاینت و سرور راه دور SSH الزامی است.
همچنین مهم است بدانید که محدودیت‌های مقصد تنها زمانی می‌توانند توسط ssh-agent(1) اعمال شوند که از یک کلید استفاده شود، یا زمانی که توسط یک ssh(1) همکار هدایت گردد. به طور مشخص، این ویژگی مانع از آن نمی‌شود که یک مهاجم دارای دسترسی به SSH_AUTH_SOCK راه دور، آن را مجدداً هدایت کرده و در یک میزبان متفاوت استفاده کند (البته تنها برای یک مقصد مجاز).
کلیدهای مقیم (resident keys) را از یک احراز هویت‌کننده FIDO بارگذاری می‌کند.
هنگام بارگذاری کلیدها در کارگزار یا حذف کلیدها از آن، تنها کلیدهای خصوصی ساده را پردازش کرده و از گواهی‌ها صرف‌نظر می‌کند.
پارامترهای کلید عمومی تمام هویت‌هایی را که در حال حاضر توسط کارگزار نگهداری می‌شوند فهرست می‌کند.
اثر انگشت تمام هویت‌هایی را که در حال حاضر توسط کارگزار نگهداری می‌شوند فهرست می‌کند.
هنگام افزودن گواهی‌ها، به‌طور پیش‌فرض ssh-add درخواست می‌کند که کارگزار پس از رسیدن تاریخ انقضای گواهی، آن را به طور خودکار حذف کند. این گزینه این رفتار را لغو کرده و طول عمری برای گواهی‌های اضافه‌شده به کارگزار تعیین نمی‌کند.
کارگزار را برای دریافت فهرست افزونه‌های پروتکلی که پشتیبانی می‌کند پرس‌وجو می‌کند. توجه: همه کارگزارها از این قابلیت پشتیبانی نمی‌کنند.
حالت بی‌صدا؛ پس از یک عملیات موفقیت‌آمیز هیچ پیامی نمایش نمی‌دهد.
مسیری را به کتابخانه‌ای مشخص می‌کند که هنگام افزودن کلیدهای میزبانی‌شده توسط احراز هویت‌کننده FIDO استفاده خواهد شد، و بر پشتیبانی داخلی پیش‌فرض USB HID اولویت خواهد داشت.
کلیدهای ارائه‌شده توسط کتابخانه مشترک PKCS#11 به نام pkcs11 را اضافه می‌کند. فایل‌های گواهی را می‌توان به‌طور اختیاری به عنوان آرگومان‌های خط فرمان مشخص کرد. در صورت وجود، آن‌ها با استفاده از هر کلید خصوصی متناظر بارگذاری‌شده از توکن PKCS#11، در کارگزار بارگذاری خواهند شد.
با انجام عملیات امضا و اعتبارسنجی روی هر یک، بررسی می‌کند که آیا کلیدهای خصوصی متناظر با فایل‌های pubkey مشخص‌شده قابل استفاده هستند یا خیر.
حداکثر طول عمر را هنگام افزودن هویت‌ها به یک کارگزار تعیین می‌کند. طول عمر را می‌توان بر حسب ثانیه یا با قالبی زمانی که در sshd_config(5) مشخص شده است تعیین کرد.
حالت پرحرف (verbose). باعث می‌شود که ssh-add پیام‌های اشکال‌زدایی مربوط به پیشرفت کار خود را چاپ کند. این گزینه در اشکال‌زدایی مشکلات بسیار مفید است. مشخص کردن چند گزینهٔ -v میزان جزئیات را افزایش می‌دهد. حداکثر تعداد مجاز ۳ است.
قفل کارگزار را باز می‌کند.
کارگزار را با یک گذرواژه قفل می‌کند.

اگر ssh-add به عبارت عبور نیاز داشته باشد، در صورتی که از یک ترمینال اجرا شده باشد، عبارت عبور را از ترمینال جاری خواهد خواند. اگر ssh-add ترمینال مرتبطی نداشته باشد اما متغیرهای DISPLAY و SSH_ASKPASS تنظیم شده باشند، برنامه‌ای را که توسط SSH_ASKPASS مشخص شده است (به‌طور پیش‌فرض ssh-askpass) اجرا کرده و یک پنجره X11 برای خواندن عبارت عبور باز می‌کند. این قابلیت به‌ویژه هنگام فراخوانی ssh-add از یک فایل .xsession یا اسکریپت مرتبط بسیار کاربردی است.
متغیر SSH_ASKPASS_REQUIRE امکان کنترل بیشتر بر استفاده از برنامه askpass را فراهم می‌کند. اگر این متغیر روی never تنظیم شده باشد، ssh-add هرگز تلاشی برای استفاده از آن نخواهد کرد. اگر روی prefer تنظیم شده باشد، ssh-add ترجیح می‌دهد هنگام درخواست گذرواژه‌ها به جای TTY از برنامه askpass استفاده کند. در نهایت، اگر این متغیر روی force تنظیم شده باشد، برنامه askpass برای تمام ورودی‌های عبارت عبور، صرف‌نظر از این‌که DISPLAY تنظیم شده باشد یا خیر، استفاده خواهد شد.
مسیر یک سوکت دامنهٔ یونیکس (Unix-domain socket) را که برای برقراری ارتباط با کارگزار استفاده می‌شود، مشخص می‌کند.
مسیری را به کتابخانه‌ای مشخص می‌کند که هنگام بارگذاری هر کلید میزبانی‌شده توسط احراز هویت‌کننده FIDO استفاده خواهد شد، و بر پشتیبانی داخلی پیش‌فرض USB HID اولویت دارد.

~/.ssh/id_ecdsa
~/.ssh/id_ecdsa_sk
~/.ssh/id_ed25519
~/.ssh/id_ed25519_sk
~/.ssh/id_mldsa44_ed25519
~/.ssh/id_rsa
حاوی هویت احراز هویت ECDSA، ECDSA میزبانی‌شده روی احراز هویت‌کننده، Ed25519، Ed25519 میزبانی‌شده روی احراز هویت‌کننده، MLDSA44-ED25519 یا RSA کاربر است.

فایل‌های هویت نباید توسط کسی جز خود کاربر قابل خواندن باشند. توجه داشته باشید که اگر فایل‌های هویت برای دیگران قابل دسترسی باشند، ssh-add آن‌ها را نادیده می‌گیرد.

وضعیت خروج در صورت موفقیت 0، در صورت شکست دستور مشخص‌شده 1، و در صورتی که ssh-add نتواند با کارگزار احراز هویت ارتباط برقرار کند 2 است.

ssh(1)، ssh-agent(1)، ssh-askpass(1)， ssh-keygen(1)， sshd(8)

پروژه OpenSSH مشتقی از نگارش اصلی و آزاد ssh 1.2.12 است که توسط Tatu Ylonen منتشر شد. Aaron Campbell، Bob Beck، Markus Friedl، Niels Provos، Theo de Raadt و Dug Song باگ‌های بسیاری را برطرف کردند، ویژگی‌های جدیدتری را افزودند و OpenSSH را به وجود آوردند. Markus Friedl پشتیبانی از نگارش‌های 1.5 و 2.0 پروتکل SSH را توسعه داد.

11 ژوئیه 2026 OpenSSH