نام (NAME)

git-http-backend - پیاده‌سازی سمت سرور گیت از طریق پروتکل HTTP

خلاصه دستور (SYNOPSIS)

git http-backend

توضیحات (DESCRIPTION)

یک برنامه ساده CGI برای ارائه محتویات یک مخزن گیت به کلاینت‌های گیت که از طریق پروتکل‌های http:// و https:// به مخزن دسترسی دارند. این برنامه هم از دریافت (fetch) کلاینت‌ها با استفاده از پروتکل هوشمند HTTP (smart HTTP) و پروتکل سازگار با گذشته سنتی HTTP (dumb HTTP)، و هم از ارسال (push) کلاینت‌ها با استفاده از پروتکل هوشمند HTTP پشتیبانی می‌کند. همچنین در صورت پیکربندی مناسب، از پروتکل کارآمدتر نسخه ۲ ("v2") گیت پشتیبانی می‌نماید؛ به توضیحات مربوط به GIT_PROTOCOL در بخش متغیرهای محیطی در ادامه مراجعه کنید.

این برنامه بررسی می‌کند که آیا دایرکتوری دارای فایل ویژه "git-daemon-export-ok" هست یا خیر، و از صادر کردن هر دایرکتوری گیت که صراحتاً به این روش برای صدور مشخص نشده باشد خودداری خواهد کرد (مگر اینکه متغیر محیطی GIT_HTTP_EXPORT_ALL تنظیم شده باشد).

به‌طور پیش‌فرض، تنها سرویس upload-pack فعال است که به کلاینت‌های git fetch-pack و git ls-remote سرویس‌دهی می‌کند؛ این کلاینت‌ها از git fetch، git pull و git clone فراخوانی می‌شوند. اگر کلاینت احراز هویت شده باشد، سرویس receive-pack فعال می‌شود که به کلاینت‌های git send-pack سرویس‌دهی می‌کند که از git push فراخوانی می‌شود.

سرویس‌ها (SERVICES)

این سرویس‌ها را می‌توان با استفاده از فایل پیکربندی هر مخزن فعال/غیرفعال کرد:

http.getanyfile

این مورد به کلاینت‌های گیت قدیمی‌تر از نسخه 1.6.6 که قادر به استفاده از سرویس upload pack نیستند سرویس‌دهی می‌کند. در صورت فعال بودن، کلاینت‌ها قادرند هر فایلی را در مخزن بخوانند، از جمله اشیایی که دیگر از طریق هیچ شاخه‌ای قابل دستیابی نیستند اما همچنان وجود دارند. این گزینه به‌طور پیش‌فرض فعال است، اما هر مخزن می‌تواند با تنظیم این مقدار پیکربندی روی false آن را غیرفعال کند.

http.uploadpack

این مورد به کلاینت‌های git fetch-pack و git ls-remote سرویس‌دهی می‌کند. این گزینه به‌طور پیش‌فرض فعال است، اما هر مخزن می‌تواند با تنظیم این مقدار پیکربندی روی false آن را غیرفعال کند.

http.receivepack

این مورد به کلاینت‌های git send-pack سرویس‌دهی کرده و اجازه push را می‌دهد. این گزینه به‌طور پیش‌فرض برای کاربران ناشناس غیرفعال و برای کاربرانی که توسط وب‌سرور احراز هویت شده‌اند فعال است. می‌توان آن را با تنظیم این مقدار روی false غیرفعال کرد، یا با تنظیم آن روی true برای همه کاربران، از جمله کاربران ناشناس، فعال نمود.

http.uploadarchive

این مورد به کلاینت‌های git archive جهت ایجاد آرشیو دوردست از طریق پروتکل‌های HTTP/HTTPS سرویس‌دهی می‌کند. این گزینه به‌طور پیش‌فرض غیرفعال است. این مورد تنها در پروتکل نسخه ۲ کار می‌کند.

ترجمه نشانی (URL TRANSLATION)

برای تعیین مکان مخزن بر روی دیسک، git http-backend متغیرهای محیطی PATH_INFO که به‌طور خودکار توسط وب‌سرور تنظیم می‌شود، و GIT_PROJECT_ROOT که باید به‌طور دستی در پیکربندی وب‌سرور تنظیم گردد را به یکدیگر متصل می‌کند. اگر GIT_PROJECT_ROOT تنظیم نشده باشد، git http-backend متغیر PATH_TRANSLATED را می‌خواند که آن نیز به‌طور خودکار توسط وب‌سرور تنظیم می‌شود.

مثال‌ها (EXAMPLES)

تمام مثال‌های زیر http://$hostname/git/foo/bar.git را به /var/www/git/foo/bar.git نگاشت می‌کنند.

Apache 2.x

اطمینان حاصل کنید که mod_cgi، mod_alias و mod_env فعال هستند، GIT_PROJECT_ROOT (یا DocumentRoot) را به‌درستی تنظیم کرده و یک ScriptAlias به این CGI ایجاد نمایید:

SetEnv GIT_PROJECT_ROOT /var/www/git
SetEnv GIT_HTTP_EXPORT_ALL
ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/
# این کار در صورت استفاده از آپاچی و نسخه مدرنی از git-http-backend
# کاملاً ضروری نیست، زیرا وب‌سرور هدر را در متغیر محیطی
# به صورت HTTP_GIT_PROTOCOL ارسال می‌کند و http-backend آن را در
# GIT_PROTOCOL کپی خواهد کرد. اما ممکن است به این خط نیاز داشته باشید
# (یا خطی مشابه اگر از وب‌سرور دیگری استفاده می‌کنید)، یا اگر می‌خواهید
# از نسخه‌های قدیمی‌تر گیت که این کپی را انجام نمی‌دادند پشتیبانی کنید.
#
# تنظیم GIT_PROTOCOL توسط وب‌سرور حتی در نسخه‌های جدید نیز کاملاً
# مناسب است (و بر HTTP_GIT_PROTOCOL تقدم خواهد داشت، به این معنی که
# می‌توان از آن برای نادیده گرفتن درخواست کلاینت استفاده کرد).
SetEnvIf Git-Protocol ".*" GIT_PROTOCOL=$0

برای فعال کردن دسترسی خواندن ناشناس اما دسترسی نوشتن با احراز هویت، برای هر دو مورد اعلان ارجاع اولیه (که آن را از طریق پارامتر service در رشته پرس‌وجو به عنوان یک push تشخیص می‌دهیم) و خود فراخوانی receive-pack به احراز هویت نیاز است:

RewriteCond %{QUERY_STRING} service=git-receive-pack [OR]
RewriteCond %{REQUEST_URI} /git-receive-pack$
RewriteRule ^/git/ - [E=AUTHREQUIRED:yes]
<LocationMatch "^/git/">
        Order Deny,Allow
        Deny from env=AUTHREQUIRED
        AuthType Basic
        AuthName "Git Access"
        Require group committers
        Satisfy Any
        ...
</LocationMatch>

اگر mod_rewrite را برای تطبیق با رشته پرس‌وجو در دسترس ندارید، کافی است تنها از خود git-receive-pack محافظت کنید، مانند:

<LocationMatch "^/git/.*/git-receive-pack$">
        AuthType Basic
        AuthName "Git Access"
        Require group committers
        ...
</LocationMatch>

در این حالت، سرور تا زمانی که کلاینت عملاً مرحله مذاکره شیء (object negotiation) عملیات push را آغاز نکند، در طول تماس اولیه درخواست احراز هویت نخواهد کرد. به همین دلیل، باید گزینه پیکربندی http.receivepack را در هر مخزنی که باید یک push را بپذیرد فعال کنید. رفتار پیش‌فرض در صورتی که http.receivepack تنظیم نشده باشد، رد هرگونه push توسط کاربران احراز هویت‌نشده است؛ بنابراین درخواست اولیه حتی بدون دادن فرصت برای احراز هویت، خطای 403 Forbidden را به کلاینت گزارش خواهد داد.

برای الزام احراز هویت برای هر دو عملیات خواندن و نوشتن، از یک دستورالعمل Location پیرامون مخزن یا یکی از دایرکتوری‌های والد آن استفاده کنید:

<Location /git/private>
        AuthType Basic
        AuthName "Private Git Access"
        Require group committers
        ...
</Location>

برای ارائه gitweb در همان نشانی وب، از ScriptAliasMatch فقط برای آن نشانی‌هایی که git http-backend می‌تواند مدیریت کند استفاده کرده و بقیه را به gitweb هدایت نمایید:

ScriptAliasMatch \
        "(?x)^/git/(.*/(HEAD | \
                        info/refs | \
                        objects/(info/[^/]+ | \
                                 [0-9a-f]{2}/[0-9a-f]{38} | \
                                 pack/pack-[0-9a-f]{40}\.(pack|idx)) | \
                        git-(upload|receive)-pack))$" \
        /usr/libexec/git-core/git-http-backend/$1
ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/

برای ارائه چند مخزن از فضاهای نام مختلف gitnamespaces(7) در یک مخزن واحد:

SetEnvIf Request_URI "^/git/([^/]*)" GIT_NAMESPACE=$1
ScriptAliasMatch ^/git/[^/]*(.*) /usr/libexec/git-core/git-http-backend/storage.git$1

Apache 2.x شتاب‌یافته برای محتوای ایستا (Accelerated static Apache 2.x)

مشابه مورد بالا، اما می‌توان از آپاچی برای بازگرداندن فایل‌های ایستای ذخیره‌شده بر روی دیسک استفاده کرد. در بسیاری از سیستم‌ها این کار می‌تواند کارآمدتر باشد زیرا آپاچی می‌تواند از هسته سیستم‌عامل بخواهد تا محتویات فایل را مستقیماً از فایل‌سیستم به شبکه کپی کند:

SetEnv GIT_PROJECT_ROOT /var/www/git
AliasMatch ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$          /var/www/git/$1
AliasMatch ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/www/git/$1
ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/

این مورد را می‌توان با پیکربندی gitweb ترکیب کرد:

SetEnv GIT_PROJECT_ROOT /var/www/git
AliasMatch ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$          /var/www/git/$1
AliasMatch ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/www/git/$1
ScriptAliasMatch \
        "(?x)^/git/(.*/(HEAD | \
                        info/refs | \
                        objects/info/[^/]+ | \
                        git-(upload|receive)-pack))$" \
        /usr/libexec/git-core/git-http-backend/$1
ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/

Lighttpd

اطمینان حاصل کنید که ماژول‌های mod_cgi، mod_alias، mod_auth، mod_setenv بارگذاری شده‌اند، سپس GIT_PROJECT_ROOT را به‌درستی تنظیم کرده و همه درخواست‌ها را به CGI هدایت کنید:

alias.url += ( "/git" => "/usr/lib/git-core/git-http-backend" )
$HTTP["url"] =~ "^/git" {
        cgi.assign = ("" => "")
        setenv.add-environment = (
                "GIT_PROJECT_ROOT" => "/var/www/git",
                "GIT_HTTP_EXPORT_ALL" => ""
        )
}

برای فعال کردن دسترسی خواندن ناشناس اما دسترسی نوشتن با احراز هویت:

$HTTP["querystring"] =~ "service=git-receive-pack" {
        include "git-auth.conf"
}
$HTTP["url"] =~ "^/git/.*/git-receive-pack$" {
        include "git-auth.conf"
}

که در آن git-auth.conf چیزی شبیه به این است:

auth.require = (
        "/" => (
                "method" => "basic",
                "realm" => "Git Access",
                "require" => "valid-user"
               )
)
# ... و پیکربندی auth.backend در اینجا

برای نیاز به احراز هویت برای هر دوی خواندن و نوشتن:

$HTTP["url"] =~ "^/git/private" {
        include "git-auth.conf"
}

متغیرهای محیطی (ENVIRONMENT)

git http-backend به متغیرهای محیطی CGI تنظیم‌شده توسط وب‌سرور فراخوان اتکا دارد، از جمله:

•PATH_INFO (اگر GIT_PROJECT_ROOT تنظیم شده باشد، در غیر این صورت PATH_TRANSLATED)

•REMOTE_USER

•REMOTE_ADDR

•CONTENT_TYPE

•QUERY_STRING

•REQUEST_METHOD

متغیر محیطی GIT_HTTP_EXPORT_ALL می‌تواند به git-http-backend ارسال شود تا بررسی وجود فایل "git-daemon-export-ok" در هر مخزن را پیش از اجازه دادن به صدور (export) آن مخزن نادیده بگیرد.

متغیر محیطی GIT_HTTP_MAX_REQUEST_BUFFER (یا گزینه پیکربندی http.maxRequestBuffer) را می‌توان برای تغییر بزرگ‌ترین درخواست مذاکره ارجاع (ref negotiation) که گیت در حین دریافت (fetch) پردازش می‌کند تنظیم کرد؛ هر دریافتی که به بافر بزرگ‌تری نیاز داشته باشد ناموفق خواهد بود. این مقدار در حالت عادی نیازی به تغییر ندارد، اما در صورتی که از مخزنی با تعداد فوق‌العاده زیادی از ارجاع‌ها دریافت انجام می‌دهید می‌تواند مفید باشد. این مقدار را می‌توان همراه با یک واحد مشخص کرد (به عنوان مثال، 100M برای ۱۰۰ مگابایت). مقدار پیش‌فرض ۱۰ مگابایت است.

کلاینت‌ها ممکن است با استفاده از هدر HTTP با نام Git-Protocol قابلیت‌های اختیاری پروتکل (مانند پروتکل v2) را بررسی کنند. به منظور پشتیبانی از این قابلیت‌ها، محتویات آن هدر باید در متغیر محیطی GIT_PROTOCOL ظاهر شود. اکثر وب‌سرورها این هدر را از طریق متغیر HTTP_GIT_PROTOCOL به CGI ارسال می‌کنند و git-http-backend به‌طور خودکار آن را در GIT_PROTOCOL کپی خواهد کرد. با این حال، برخی از وب‌سرورها ممکن است در انتخاب هدرهایی که ارسال می‌کنند گزینشی‌تر عمل کنند، که در این صورت باید به‌طور صریح پیکربندی شوند (به ذکر Git-Protocol در پیکربندی آپاچی در بخش مثال‌ها در بالا مراجعه کنید).

فرآیند بک‌اند متغیر GIT_COMMITTER_NAME را روی $REMOTE_USER و GIT_COMMITTER_EMAIL را روی ${REMOTE_USER}@http.${REMOTE_ADDR} تنظیم می‌کند، و بدین ترتیب تضمین می‌نماید که هرگونه reflog ایجادشده توسط git-receive-pack حاوی اطلاعات هویتی کاربری دوردستی باشد که ارسال (push) را انجام داده است.

تمام متغیرهای محیطی CGI برای هر یک از قلاب‌ها (hooks) که توسط git-receive-pack فراخوانی می‌شوند در دسترس هستند.

همچنین ببینید (SEE ALSO)

git(1), git-daemon(1), githooks(5), gitnamespaces(7)

گیت (GIT)

بخشی از مجموعه git(1)