GPG-CONNECT-AGENT(1) دستورهای کاربری GPG-CONNECT-AGENT(1)

gpg-connect-agent - برقراری ارتباط و ارسال فرمان به دیمن در حال اجرای gpg-agent

gpg-connect-agent [ گزینهها ] [ دستورات... ]

دستور gpg-connect-agent ابزاری است برای برقراری ارتباط مستقیم با پردازش دیمن gpg-agent و ارسال دستورات سطح پروتکل Assuan. این ابزار جهت بررسی و آزمایش دستوراتی که gpg-agent از طریق واسط Assuan ارائه می‌دهد، بسیار کاربردی است. همچنین می‌تواند برای اسکریپت‌نویسی برنامه‌های ساده نیز مفید باشد. ورودی از ورودی استاندارد (stdin) دریافت شده و خروجی در خروجی استاندارد (stdout) چاپ می‌شود.

عملکرد این ابزار بسیار شبیه به اجرای gpg-agent در حالت سرور (server mode) است؛ اما در اینجا اتصال به یک نمونه در حال اجرا برقرار می‌شود.

گزینه‌های زیر می‌توانند استفاده شوند:

به‌جای gpg-agent به یک مدیر دایرکتوری در حال اجرا (کلاینت سرور کلید یا keyserver) متصل می‌شود. اگر dirmngr در حال اجرا نباشد، آن را راه‌اندازی می‌کند.
به‌جای gpg-agent به یک دیمن keybox در حال اجرا متصل می‌شود. اگر keyboxd در حال اجرا نباشد، آن را راه‌اندازی می‌کند.
به سوکت نام با این فرض که یک سرور مبتنی بر پروتکل Assuan است متصل می‌شود. هیچ‌گونه مقداردهی اولیه یا بررسی محیطی ویژه انجام نمی‌دهد. از این گزینه می‌توان برای اتصال مستقیم به هر سرور سوکت به سبک Assuan استفاده کرد.
باقی‌مانده خط فرمان را به عنوان یک برنامه و آرگومان‌های آن در نظر گرفته و آن را به عنوان یک سرور Assuan اجرا می‌کند. نحوه اجرای gpgsm به عنوان نمونه به این شکل خواهد بود:
gpg-connect-agent --exec gpgsm --server
توجه داشته باشید که در این حالت نمی‌توانید از گزینه‌های دیگر در خط فرمان استفاده کنید.
هنگام اجرا، اطلاعات تکمیلی و با جزئیات بیشتر را نمایش می‌دهد.
تلاش می‌کند تا حد امکان بدون خروجی اضافی (بی‌صدا) اجرا شود.
--homedir پوشه
نام پوشه خانگی را برابر با پوشه قرار می‌دهد. در صورت عدم استفاده از این گزینه، پوشه خانگی به‌صورت پیش‌فرض برابر با ‘~/.gnupg’ خواهد بود. این گزینه تنها زمانی شناسایی می‌شود که در خط فرمان داده شده باشد. همچنین هر پوشه خانگی تعیین‌شده از طریق متغیر محیطی ‘GNUPGHOME’ یا (در سیستم‌های ویندوز) از طریق مدخل رجیستری HKCU\Software\GNU\GnuPG:HomeDir را بازنویسی می‌کند.

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

کاربر فعلی را به uid تغییر می‌دهد که می‌تواند یک عدد شناسه یا یک نام کاربری باشد. از این گزینه می‌توان از طریق حساب کاربر ارشد (root) برای اجرای gpg-connect-agent برای کاربری دیگر استفاده کرد. اگر uid شناسه کاربری فعلی نباشد، متغیر PATH استاندارد تنظیم شده و متغیر محیطی GNUPGHOME حذف می‌شود. برای نادیده گرفتن مورد دوم، می‌توان از گزینه --homedir استفاده کرد. این گزینه تنها در صورتی اثرگذار است که در خط فرمان استفاده شود. این گزینه در حال حاضر در ویندوز هیچ تاثیری ندارد.
هنگام استفاده از -S یا --exec، ابزار gpg-connect-agent به منظور امکان انتقال توصیف‌گر (descriptor passing) به سرور Assuan در حالت توسعه‌یافته متصل می‌شود. این گزینه باعث می‌شود که از حالت قدیمی استفاده شود.
در صورتی که gpg-agent یا dirmngr هنوز اجرا نشده باشند، آن‌ها را به‌صورت خودکار آغاز نمی‌کند.
در حالت تعاملی (interactive)، تاریخچه خط فرمان معمولاً در فایلی زیر پوشه خانگی GnuPG ذخیره و بازیابی می‌شود. این گزینه از استفاده از آن فایل جلوگیری می‌کند.
برنامه agent را مشخص می‌کند تا در صورتی که هیچ برنامه‌ای در حال اجرا نباشد، آغاز شود. مقدار پیش‌فرض با اجرای gpgconf همراه با گزینه --list-dirs تعیین می‌شود. توجه داشته باشید که علامت پایپ (|) برای ترفندی در مجموعه آزمون‌های پس‌رفت (regression test suite) استفاده می‌شود و نباید در نام فایل قرار گیرد.
--dirmngr-program فایل
برنامه مدیر دایرکتوری (کلاینت keyserver) را مشخص می‌کند تا در صورت در حال اجرا نبودن، آغاز شود. این گزینه تنها زمانی اثر دارد که همراه با گزینه --dirmngr استفاده شود.
--keyboxd-program فایل
برنامه دیمن keybox را مشخص می‌کند تا در صورت در حال اجرا نبودن، آغاز شود. این گزینه تنها زمانی اثر دارد که همراه با گزینه --keyboxd استفاده شود.
دستورات موجود در فایل را در زمان راه‌اندازی اجرا کرده و سپس با روش ورودی معمول ادامه می‌دهد. توجه داشته باشید دستوراتی که در خط فرمان داده می‌شوند پس از این فایل پردازش و اجرا خواهند شد.
دستور /subst را در هنگام راه‌اندازی اجرا می‌کند.
سطرهای داده را در قالب هگزادسیمال و نمایش اسکی نویسه‌های غیرکنترلی چاپ می‌کند.
سطرهای داده را رمزگشایی (decode) می‌کند؛ یعنی فرارهای درصدی (percent escapes) را حذف می‌کند اما اطمینان می‌دهد که هر سطر جدید همیشه با یک حرف D و یک فاصله آغاز شود.
ورودی استاندارد (stdin) و خروجی استاندارد (stdout) را در حالت ورودی/خروجی بدون بافر قرار می‌دهد. این گزینه گاهی برای اسکریپت‌نویسی مفید است.

هنگام خواندن دستورات Assuan، برنامه gpg-agent همچنین به چند دستور ویژه اجازه می‌دهد تا عملکرد آن را کنترل کنند. تمامی این دستورات کنترلی با یک اسلش (/) آغاز می‌شوند.

/echo آرگومان‌ها
صرفاً آرگومان‌ها را چاپ می‌کند.
/let نام مقدار
متغیر نام را برابر با مقدار قرار می‌دهد. متغیرها تنها در صورتی در ورودی جایگزین می‌شوند که از دستور /subst استفاده شده باشد. متغیرها با افزودن یک علامت دلار در ابتدای نام ارجاع داده می‌شوند و می‌توان نام را به صورت اختیاری درون آکولاد قرار داد. قوانین نام‌گذاری معتبر دقیقاً مشابه قوانین استاندارد شل بورن (Bourne shell) است. این موضوع هنوز اجباری نشده است اما ممکن است در آینده چنین شود. هنگام استفاده از آکولاد، هیچ فاصله خالی در ابتدا یا انتهای نام مجاز نیست.

اگر متغیری پیدا نشود، در متغیرهای محیطی جستجو می‌شود و در صورت یافتن، در جدول متغیرها کپی می‌گردد.

توابع متغیر در دسترس هستند: نام تابع باید با حداقل یک فاصله و سپس حداقل یک آرگومان دنبال شود. توابع زیر موجود هستند:

مقداری را که توسط آرگومان توصیف شده است برمی‌گرداند. آرگومان‌های مجاز عبارتند از:
دایرکتوری کاری فعلی.
پوشه خانگی gnupg.
دایرکتوری پیکربندی سیستمی GnuPG.
دایرکتوری باینری‌های GnuPG.
دایرکتوری کتابخانه‌های GnuPG.
دایرکتوری فایل‌های اجرایی کتابخانه‌ای GnuPG.
دایرکتوری داده‌های GnuPG.
شناسه پردازش (PID) سرور فعلی. برای بازگرداندن یک مقدار مفید، باید دستور /serverpid قبلاً صادر شده باشد.
فرارهای به سبک C را از آرگومان‌ها حذف می‌کند. توجه داشته باشید که \0 و \x00 به‌صورت ضمنی به رشته بازگردانده‌شده خاتمه می‌دهند. رشته‌ای که باید تبدیل شود کل آرگومان‌های بلافاصله پس از فاصله جداکننده نام تابع است.
فرارهای به سبک درصدی را از آرگومان‌ها حذف می‌کند. توجه داشته باشید که %00 به‌طور ضمنی رشته را خاتمه می‌دهد. رشته‌ای که باید تبدیل شود کل آرگومان‌های بلافاصله پس از فاصله جداکننده نام تابع است. دستور unpercent+ همچنین علامت‌های جمع را به فاصله نگاشت می‌کند.
با استفاده از روش فرار درصدی، کاراکترهای فرار را به آرگومان‌ها اعمال می‌کند. کلیدهای تب، انتقال صفحه (formfeed)، سرخط (linefeed)، بازگشت به ابتدای سطر (carriage return) و دو‌نقطه فرار داده می‌شوند. دستور percent+ همچنین فاصله‌ها را به علامت‌های جمع نگاشت می‌کند.
فرض می‌کند که آرگومان یک عدد صحیح است و آن را با استفاده از strtol ارزیابی می‌کند. کد خطای gpg-error، منبع خطا یا رشته‌ای قالب‌بندی‌شده شامل کد خطا و منبع خطا را بازمی‌گرداند.
+
-
*
/
%
تمام آرگومان‌ها را با استفاده از strtol به عنوان اعداد صحیح بزرگ (long) ارزیابی کرده و این عملگر را روی آن‌ها اعمال می‌کند. تقسیم بر صفر یک رشته خالی برمی‌گرداند.
!
|
&
تمام آرگومان‌ها را با استفاده از strtol به عنوان اعداد صحیح بزرگ ارزیابی کرده و عملگرهای منطقی NOT، OR یا AND را اعمال می‌کند. عملگر NOT تنها روی آخرین آرگومان اعمال می‌شود.
/definq نام متغیر
از محتوای متغیر متغیر برای پرس‌وجوهای (inquiries) منطبق با نام استفاده می‌کند. نام می‌تواند یک علامت ستاره (*) باشد تا با هر پرس‌وجویی تطابق یابد.
/definqfile نام فایل
از محتوای فایل برای پرس‌وجوهای منطبق با نام استفاده می‌کند. نام می‌تواند یک علامت ستاره (*) باشد تا با هر پرس‌وجویی تطابق یابد.
/definqprog نام برنامه
برنامه برنامه را برای پرس‌وجوهای منطبق با نام اجرا کرده و کل سطر را به عنوان آرگومان‌های خط فرمان به آن ارسال می‌کند.
/datafile نام
تمام سطرهای داده دریافت‌شده از سرور را در فایل نام می‌نویسد. فایل برای نوشتن باز شده و در صورت عدم وجود ایجاد می‌شود. اگر فایل از قبل موجود باشد، ابتدا طول آن به ۰ تقلیل می‌یابد. داده‌های نوشته‌شده در فایل کاملاً رمزگشایی (decode) می‌شوند. استفاده از یک خط تیره تکی برای نام باعث نوشتن در خروجی استاندارد (stdout) می‌شود. این فایل تا زمانی که فایل جدیدی با این دستور تنظیم شود یا این دستور بدون آرگومان فراخوانی شود، باز می‌ماند.
/showdef
تمام تعاریف را چاپ می‌کند.
/cleardef
تمام تعاریف را پاک می‌کند.
/sendfd فایل حالت
فایل فایل را در حالت حالت (که باید یک رشته معتبر برای حالت تابع fopen باشد) باز کرده و توصیف‌گر فایل (file descriptor) را به سرور ارسال می‌کند. این دستور معمولاً با فرمانی مانند INPUT FD برای تنظیم منبع ورودی برای سایر دستورات دنبال می‌شود.
/recvfd
هنوز پیاده‌سازی نشده است.
/open متغیر فایل [حالت]
فایل فایل را باز کرده و توصیف‌گر فایل را به متغیر اختصاص می‌دهد. هشدار: این دستور آزمایشی است و ممکن است در نسخه‌های بعدی تغییر کند.
/close fd
توصیف‌گر فایل fd را می‌بندد. هشدار: این دستور آزمایشی است و ممکن است در نسخه‌های بعدی تغییر کند.
/showopen
فهرستی از فایل‌های باز را نمایش می‌دهد.
/serverpid
دستور Assuan با عنوان GETINFO pid را به سرور ارسال کرده و شناسه پردازش (PID) بازگردانده‌شده را برای مصارف داخلی ذخیره می‌کند.
/sleep
به مدت یک ثانیه توقف موقت (sleep) می‌کند.
/hex
/nohex
مشابه گزینه خط فرمان --hex است.
/decode
/nodecode
مشابه گزینه خط فرمان --decode است.
/subst
/nosubst
جایگزینی متغیرها را فعال یا غیرفعال می‌کند. به صورت پیش‌فرض غیرفعال است مگر اینکه از گزینه خط فرمان --subst استفاده شده باشد. اگر /subst یک‌بار فعال شود، فاصله‌های خالی ابتدای سطرهای ورودی حذف می‌شوند که خوانایی اسکریپت‌ها را آسان‌تر می‌کند.
/while شرط
/end
این دستورات روشی برای اجرای حلقه‌ها فراهم می‌کنند. تمام سطرهای میان while و end متناظر، تا زمانی اجرا می‌شوند که ارزیابی شرط مقداری غیر از صفر داشته باشد یا رشته true یا yes باشد. ارزیابی شرط با انتقال شرط به تابع strtol انجام می‌شود. مثال:
/subst
/let i 3
/while $i
  /echo loop counter is $i
  /let i ${- $i 1}
/end
/if شرط
/end
این دستورات روشی برای اجرای شرطی فراهم می‌کنند. تمام سطرهای میان if و end متناظر، تنها در صورتی اجرا می‌شوند که ارزیابی شرط مقداری غیر از صفر داشته باشد یا رشته true یا yes باشد. ارزیابی شرط با انتقال شرط به تابع strtol انجام می‌شود.
/run فایل
دستورات را از فایل اجرا می‌کند.
/history --clear
تاریخچه دستورات را پاک می‌کند.
/bye
اتصال و برنامه را خاتمه می‌دهد.
/help
فهرستی از دستورات کنترلی در دسترس را چاپ می‌کند.

gpg-agent(1), scdaemon(1)

مستندات کامل این ابزار به عنوان یک راهنمای Texinfo نگهداری می‌شود. اگر GnuPG و برنامه info به درستی در سیستم شما نصب شده باشند، اجرای دستور

info gnupg
باید امکان دسترسی به راهنمای کامل شامل ساختار منو و نمایه را برای شما فراهم کند.
مه ۲۰۲۵ gnupg