.\"  -*- nroff -*-
.\"
.\" Author: Carson Harding
.\" Copyright (c) 2002-2018 Carson Harding. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted.
.\"
.\" 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.
.\"
.\" $Id: autossh.1,v 1.24 2018/03/18 19:28:38 harding Exp $
.\"
.Dd Mar 18, 2018
.Dt AUTOSSH 1
.Os
.Sh "نام (NAME)"
.Nm autossh
.Nd نظارت و راه‌اندازی مجدد خودکار نشست‌های SSH
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm autossh
.Op Fl V
.Op Fl M Ar port[:echo_port]
.Op Fl f
.Ar [SSH_OPTIONS]
.Sh "توضیحات (DESCRIPTION)"
.Nm
برنامه‌ای برای راه‌اندازی و نظارت بر یک نسخه از ssh است که در صورت متوقف شدن یا قطع انتقال ترافیک، آن را بر حسب نیاز مجدداً راه‌اندازی می‌کند.
.Pp
ایده اولیه و سازوکار این ابزار از rstunnel (تونل SSH مطمئن) گرفته شده است. از نسخه ۱.۲
.Nm
روش کار تغییر کرد:
.Nm
از ssh برای ایجاد یک حلقه از فورواردهای ssh (یکی از سیستم محلی به دوردست، و دیگری از دوردست به محلی) استفاده می‌کند و سپس داده‌های آزمایشی را ارسال کرده و منتظر بازگشت آن‌ها می‌ماند. (این ایده با تشکر از ترنس مارتین / Terrence Martin است.)
.Pp
از نسخه ۱.۳، یک روش جدید اضافه شد (با تشکر از ران یورستون / Ron Yorston): می‌توان یک پورت را برای یک سرویس echo دوردست تعیین کرد تا داده‌های آزمایشی را بازتاب دهد. این کار از ترافیک اضافی و دردسر اطمینان از تداخل نداشتن تمام شماره پورت‌ها در رایانه دوردست جلوگیری می‌کند. روش حلقه فورواردها برای شرایطی که امکان استفاده از سرویس echo وجود ندارد، همچنان در دسترس است.
.Sh "کنترل SSH (CONTROLLING SSH)"
.Ss "خروج‌های SSH (SSH exits)"
.Nm
تلاش می‌کند نحوه خاتمه یافتن فرآیند ssh تحت نظارت خود را تشخیص دهد و واکنش مناسب نشان دهد. قوانین به این شرح است:
.Bl -tag -width Ds
.It 1.
اگر فرآیند ssh به صورت عادی خارج شود (برای مثال، شخصی در یک نشست تعاملی دستور
.Dq exit
را تایپ کند)،
.Nm
به جای راه‌اندازی مجدد، خارج می‌شود؛
.It 2.
اگر خود
.Nm
سیگنال SIGTERM، SIGINT یا SIGKILL دریافت کند، فرض می‌کند که به صورت عمدی به آن سیگنال داده شده است و پس از کشتن فرآیند فرزند ssh، خارج می‌شود؛
.It 3.
اگر خود
.Nm
سیگنال SIGUSR1 دریافت کند، فرآیند فرزند ssh را می‌کشد و فرآیند جدیدی را آغاز می‌کند؛
.It 4.
به صورت دوره‌ای (به طور پیش‌فرض هر ۱۰ دقیقه یک‌بار)،
.Nm
تلاش می‌کند ترافیکی را از پورت فوروارد شده نظارتی عبور دهد. اگر این کار با شکست مواجه شود،
.Nm
فرآیند فرزند ssh را (در صورت در حال اجرا بودن) می‌کشد و فرآیند جدیدی را شروع می‌کند؛
.It 5.
اگر فرآیند فرزند ssh به هر دلیل دیگری خاتمه یابد،
.Nm
تلاش خواهد کرد فرآیند جدیدی را راه‌اندازی کند.
.El
.Pp
.Ss "رفتار هنگام راه‌اندازی (Startup behaviour)"
اگر نشست ssh در همان اولین تلاش با وضعیت خروج ۱ شکست بخورد،
.Nm
.Bl -tag -width Ds
.It 1.
فرض خواهد کرد که مشکلی در نحو یا پیکربندی اتصال وجود دارد و به جای تلاش مجدد، خارج خواهد شد؛
.It 2.
یک زمان «دروازه آغازین» (starting gate) وجود دارد. اگر اولین فرآیند ssh در چند ثانیه نخست پس از شروع با شکست مواجه شود،
.Nm
فرض می‌کند که هرگز موفق به خروج از «دروازه آغازین» نشده است و خارج می‌شود. این ویژگی برای مدیریت شکست‌های اولیه در احراز هویت، برقراری اتصال و موارد مشابه است. این زمان به طور پیش‌فرض ۳۰ ثانیه است و می‌توان آن را تنظیم کرد (متغیر محیطی AUTOSSH_GATETIME را در زیر ببینید). اگر AUTOSSH_GATETIME برابر ۰ تنظیم شود، هر دو رفتار غیرفعال می‌شوند: دیگر هیچ «دروازه آغازینی» وجود ندارد و autossh حتی اگر ssh در نخستین اجرا با وضعیت خروج ۱ شکست بخورد، مجدداً آن را راه‌اندازی می‌کند. زمان «دروازه آغازین» همچنین هنگامی که فلگ
.Fl f
برای autossh استفاده شود، روی ۰ تنظیم می‌گردد.
.El
.Pp
.Ss "شکست‌های پیاپی (Continued failures)"
اگر اتصال ssh قطع شود و تلاش‌ها برای راه‌اندازی مجدد آن پشت سر هم با شکست مواجه شوند،
.Nm
شروع به ایجاد تاخیر در تلاش‌های راه‌اندازی مجدد خود می‌کند و به تدریج فاصله زمانی را بیشتر و بیشتر می‌نماید تا اینکه به حداکثر بازه زمانی دوره نظرسنجی (poll time)
.Nm
(معمولاً ۱۰ دقیقه) برسد. می‌توان با ارسال سیگنال به
.Nm
، احتمالاً با SIGHUP (مانند
.Dq kill \-HUP
)، آن را برای تلاش مجدد تحریک کرد.
.Pp
.Ss "راه‌اندازی اتصال (Connection setup)"
از آنجا که اتصال‌ها باید بدون نیاز به دخالت کاربر برقرار شوند، استفاده از
.Nm
مستلزم پیکربندی نوعی احراز هویت خودکار است. استفاده از RSAAuthentication به همراه ssh-agent روش پیشنهادی است. اسکریپت پوششی نمونه (wrapper) بررسی می‌کند که آیا یک agent برای محیط جاری در حال اجرا است یا خیر، و اگر در حال اجرا نباشد یکی را راه‌اندازی می‌کند.
.Pp
تاکید بر این موضوع هرگز زیاده‌روی نیست که ابتدا باید مطمئن شوید ssh به تنهایی و به درستی کار می‌کند، و می‌توانید نشست مورد نظر خود را برقرار کنید، پیش از آنکه تلاش نمایید آن را تحت نظارت
.Nm
اجرا کنید.
.Pp
اگر از قابلیت تونل‌زنی استفاده می‌کنید و نسخه‌ای قدیمی از ssh را به کار می‌برید که از فلگ
.Fl N
پشتیبانی نمی‌کند، باید آن را ارتقا دهید (نسخه شما دارای اشکالات امنیتی است). اگر امکان ارتقا ندارید، می‌توانید همانند rstunnel عمل کرده و دستوری مانند
.Dq sleep 99999999999
را برای اجرا به ssh بدهید.
.Sh "گزینه‌ها (OPTIONS)"
.Bl -tag -width Ds
.It Fl M Ar port[:echo_port]
پورت پایه نظارتی را برای استفاده مشخص می‌کند. بدون پورت echo، این پورت و پورت بلافاصله بعد از آن (
.Ar port
+ 1) باید اعدادی باشند که هیچ سرویس دیگری از آن‌ها استفاده نمی‌کند.
.Nm
داده‌های آزمایشی را روی پورت پایه نظارت ارسال می‌کند و آن‌ها را روی پورت بعدی دریافت می‌نماید. برای مثال، اگر
.Dq Fl M\ 20000
را مشخص کنید،
.Nm
فورواردها را طوری پیکربندی می‌کند که بتواند داده‌ها را روی پورت ۲۰۰۰۰ ارسال کرده و روی پورت ۲۰۰۱ بازپس گیرد.
.Pp
همچنین، می‌توان پورتی را برای یک سرویس echo دوردست مشخص کرد. در صورت تمایل به استفاده از سرویس استاندارد inetd echo، این مقدار باید پورت ۷ باشد. هنگامی که یک پورت echo مشخص شود، تنها پورت نظارتی تعیین‌شده به کار گرفته می‌شود و پیام‌های نظارتی را در هر دو جهت منتقل می‌کند.
.Pp
بسیاری از افراد سرویس echo یا حتی inetd را غیرفعال می‌کنند، بنابراین بررسی کنید که آیا این سرویس روی رایانه دوردست در دسترس است یا خیر. برخی سیستم‌های عامل اجازه می‌دهند که سرویس تنها روی localhost (رابط loopback) شنود کند، که برای این کاربرد کفایت می‌کند.
.Pp
سرویس echo همچنین می‌تواند ساختار پیچیده‌تری داشته باشد؛ برای مثال، دیمنی که بر گروهی از تونل‌های ssh نظارت می‌کند.
.Pp
تنظیم پورت نظارت روی ۰ قابلیت نظارت را خاموش می‌کند، و در این حالت autossh تنها پس از خروج ssh آن را مجدداً راه‌اندازی می‌نماید. برای مثال، اگر از نسخه‌های جدید OpenSSH استفاده می‌کنید، ممکن است ترجیح دهید از گزینه‌های
.Cm ServerAliveInterval
و
.Cm ServerAliveCountMax
استفاده کنید تا در صورتی که کلاینت SSH متوجه شود ارتباطش با سرور قطع شده است، خودبه‌خود خارج شود. از بسیاری جهات، این روش می‌تواند راهکار بهتری نسبت به استفاده از پورت نظارتی باشد.
.It Fl f
باعث می‌شود autossh پیش از اجرای ssh به پس‌زمینه برود. فلگ
.Fl f
از میان آرگومان‌های ارسالی به ssh حذف می‌شود. توجه داشته باشید که یک تفاوت اساسی میان
.Fl f
در autossh و
.Fl f
در ssh وجود دارد: هنگامی که همراه با
.Nm
استفاده شود، ssh قادر به درخواست گذرواژه یا عبارت عبور (passphrase) نخواهد بود. همچنین زمانی که
.Fl f
به کار رود، زمان «دروازه آغازین» (AUTOSSH_GATETIME را ببینید) روی ۰ تنظیم می‌گردد.
.It Fl V
باعث می‌شود
.Nm
شماره نسخه خود را نمایش دهد و خارج شود.
.El
.Sh "محیط (ENVIRONMENT)"
به غیر از فلگی که برای تنظیم پورت نظارت بر اتصال وجود دارد،
.Nm
برای کنترل قابلیت‌های خود از متغیرهای محیطی استفاده می‌کند. به نظر می‌رسد ssh همچنان در حال تخصیص حروف مختلف به گزینه‌های خود است و این روش آسان‌ترین راه برای جلوگیری از تداخل گزینه‌هاست.
.Bl -tag -width Ds
.It Ev AUTOSSH_DEBUG
در صورت تنظیم این متغیر، سطح گزارش‌گیری روی LOG_DEBUG قرار می‌گیرد و اگر سیستم‌عامل پشتیبانی کند، syslog ورودی‌های گزارش را روی خروجی خطای استاندارد (stderr) نیز ارسال می‌کند.
.It Ev AUTOSSH_FIRST_POLL
مدت زمانی را که باید قبل از انجام اولین آزمون اتصال منتظر ماند، مشخص می‌کند. پس از آن، زمان عمومی نظرسنجی مورد استفاده قرار می‌گیرد (AUTOSSH_POLL را در زیر ببینید).
.It Ev AUTOSSH_GATETIME
مشخص می‌کند که ssh چه مدت باید فعال بماند تا اتصال آن موفقیت‌آمیز تلقی شود. مقدار پیش‌فرض ۳۰ ثانیه است. توجه داشته باشید که اگر AUTOSSH_GATETIME برابر ۰ تنظیم شود، نه تنها رفتار دروازه آغازین خاموش می‌شود، بلکه autossh شکست نخستین اجرای ssh را نیز نادیده می‌گیرد. این امر می‌تواند هنگام اجرای autossh در زمان راه‌اندازی سیستم (بوت) مفید باشد.
.It Ev AUTOSSH_LOGLEVEL
سطح گزارش‌گیری را متناسب با سطوح مورد استفاده در syslog تعیین می‌کند؛ یعنی مقادیر ۰ تا ۷ که در آن ۷ پرجزئیات‌ترین حالت است.
.It Ev AUTOSSH_LOGFILE
مشخص می‌کند که
.Nm
باید به جای syslog، از فایل گزارش تعیین‌شده استفاده کند.
.It Ev AUTOSSH_MAXLIFETIME
حداکثر تعداد ثانیه‌هایی را که برنامه باید اجرا شود تنظیم می‌کند. پس از سپری شدن این مدت زمان، فرآیند فرزند ssh کشته شده و برنامه خارج می‌شود.
.It Ev AUTOSSH_MAXSTART
تعداد دفعاتی را که ssh باید راه‌اندازی شود مشخص می‌کند. عدد منفی به معنای نامحدود بودن تعداد دفعات راه‌اندازی ssh است. مقدار پیش‌فرض \-1 است.
.It Ev AUTOSSH_MESSAGE
پیامی را به پیام echo ارسالی هنگام آزمایش اتصال‌ها اضافه می‌کند.
.It Ev AUTOSSH_NTSERVICE
(تنها در سیگوین / Cygwin.) زمانی که روی
.Dq yes
تنظیم شود، autossh طوری پیکربندی می‌گردد که به عنوان یک سرویس NT تحت cygrunsrv اجرا شود. این کار فلگ
.Fl N
را در صورت تنظیم نبودن به ssh اضافه می‌کند، خروجی گزارش‌ها را به stdout هدایت می‌نماید و رفتار خروج ssh را تغییر می‌دهد تا حتی در صورت خروج عادی نیز مجدداً راه‌اندازی شود.
.It Ev AUTOSSH_PATH
مسیر فایل اجرایی ssh را در صورتی که با مسیر کامپایل‌شده تفاوت داشته باشد مشخص می‌کند.
.It Ev AUTOSSH_PIDFILE
شناسه فرآیند (PID) برنامه autossh را در فایل مشخص‌شده می‌نویسد.
.It Ev AUTOSSH_POLL
زمان نظرسنجی اتصال را به ثانیه مشخص می‌کند؛ پیش‌فرض ۶۰۰ ثانیه (۱۰ دقیقه) است. مگر اینکه از AUTOSSH_FIRST_POLL استفاده شده باشد، زمان اولین نظرسنجی برابر با همین زمان نظرسنجی تنظیم خواهد شد. اگر زمان نظرسنجی کمتر از دو برابر مهلت زمانی شبکه (پیش‌فرض ۱۵ ثانیه) باشد، مهلت‌های زمانی شبکه به نصف زمان نظرسنجی کاهش می‌یابند.
.It Ev AUTOSSH_PORT
پورت نظارت بر اتصال را تنظیم می‌کند. این متغیر بیشتر برای زمانی در نظر گرفته شده که ممکن است ssh در آینده از فلگ \-M برای منظوری دیگر استفاده کند. با توجه به این احتمال، مقدار AUTOSSH_PORT اولویت بیشتری نسبت به فلگ \-M دارد و آن را بازنویسی می‌کند. مقدار ۰ عملکرد نظارت را خاموش می‌کند.
.El
.Sh "محیط (ENVIRONMENT)"
دو گزینه خاص در OpenSSH وجود دارند که هنگام استفاده از
.Nm
بسیار سودمند هستند:
.Pp
.Cm ExitOnForwardFailure=yes
در سمت کلاینت برای اطمینان از موفقیت فورواردها هنگامی که autossh فرض می‌کند اتصال به درستی برقرار شده است.
.Pp
.Cm ClientAliveInterval
در سمت سرور برای اطمینان از بسته شدن سوکت شنود در سمت سرور در صورتی که اتصال در سمت کلاینت بسته شود.
.Sh "نویسنده (AUTHOR)"
.Nm
توسط Carson Harding نوشته شده است.
.Sh "همچنین ببینید (SEE ALSO)"
.Xr ssh 1 ,
.Xr ssh_config 5,
.Xr sshd_config 5,
.Xr ssh\-add 1 ,
.Xr ssh\-agent 1 ,
.Xr ssh\-keygen 1 ,
.Xr cygrunsrv 1 .