WAYJAM

GitLab Shell如何通过SSH工作

GitLab访问Git仓库

首先回顾GitLab的Git仓库四种访问方式:

  1. git pull over http -> gitlab-rails (Authorization) -> accept or decline -> execute git command
  2. git push over http -> gitlab-rails (git command is not executed yet) -> execute git command -> gitlab-shell pre-receive hook -> API call to gitlab-rails (authorization) -> accept or decline push
  3. git pull over ssh -> gitlab-shell -> API call to gitlab-rails (Authorization) -> accept or decline -> execute git command
  4. git push over ssh -> gitlab-shell (git command is not executed yet) -> execute git command -> gitlab-shell pre-receive hook -> API call to gitlab-rails (authorization) -> accept or decline push

四种方式都有GitLab Shell的参与,但不同过程GitLab Shell发挥了不同的作用,并且它并不是一个整体的服务,而是由一些子命令组合而成。HTTP方式的Git操作,经gitlab workhorse直接交由Rails应用处理,然后通过HTTP协议交换数据,对于git的操作有三条路径:Gem包Rugged、Raw Git命令或者Gitaly,push/pull一般只跟后两种有关,GitLab Shell充当的作用仅仅是git hook的作用。

SSH方式的push/pull是GitLab Shell的主场景,而Rails在这其中充当了权限再验证的角色。

Git SSH 传输协议

首先,简要说明Git是如何通过SSH协议与服务端的Git交互数据。

ssh git@example.com "the-command"

在客户端执行这样的命令时候,服务端SSHD验证身份通过后,默认将启动一个Shell解析执行the-command的命令。普通使用中,大多都不加自定义命令,这将启动一个Shell交互式命令解析器。

要了解GitLab Shell的原理,不能不说它的“前任”——Gitolite。Gitolite是一个Git的授权层前端,同样提供了HTTP(httpd)和SSH的方式访问Git仓库。而Gitlab在v5.0完全用GitLab Shell替代了Gitolite,前者完全依赖Rails层的权限认证(项目、分支、用户等的权限),后者则由于需要完全保持一份冗余数据在自身的配置文件,主要由于速度和数据不同步被Gitlab官方放弃。但是,二者仍然采用了authorized_keyscommand magic方案。

GitLab CE 10.4之后加入了`AuthorizedKeysCommand`的使用(_require_ OpenSSH 6.9+),使用自定义程序匹配Key而不是文件文本匹配。

SSH command magic

SSHD服务端收到客户端的连接请求后,会在authorized_keys进行匹配,认证失败则拒绝连接。查看~/.ssh/authorized_keys文件内容如下:

# Gitolite
command="[path]/gitolite-shell user-one",[more options] ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEArXtCT...
# GitLab Shell
command="/home/git/gitlab-shell/bin/gitlab-shell key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEArXtCT...

可以发现保存的每条公钥前面都有command=,Gitolite和GitLab Shell后面的参数代表着用户的识别信息,Gitolite保存在配置文件,而gitlab保存在数据库。当用户的服务端校验成功后,则会执行command=后的命令,而不是shell access,同时将SSH命令所要执行的命令赋值给SSH_ORIGINAL_COMMAND。所以与客户端交互的真正命令是(以pull代码为例):

SSH_ORIGINAL_COMMAND=git-upload-pack git-pack/home/git/gitlab-shell/bin/gitlab-shell key-1

"Shell"

GitLab Shell由ruby脚本和go程序组成,首先看GitLab Shell入口代码:bin/gitlab-shell

#!/usr/bin/env ruby
# ...
key_id = /key-[0-9]+/.match(ARGV.join).to_s
original_cmd = ENV.delete('SSH_ORIGINAL_COMMAND')
# ...
require File.join(ROOT_PATH, 'lib', 'gitlab_shell')
if GitlabShell.new(key_id).exec(original_cmd)
# ...

这段代码里面的两个变量:

  • key_id -> sshd调用GitLab Shell时传入的参数。
  • original_cmd -> 即上文提到的SSH_ORIGINAL_COMMAND环境变量,并且获取完即移除。

举个例子,如果用户通过git客户端调用git clone git@server的时候,实际上git客户端启动的是receive-pack(git由许许多多子命令组成)并且在内部执行的是ssh git@git@server git-upload-pack git@server,那么此时,服务端给GitLab Shell设定的环境变量则是git-upload-pack git@server,。

然后看lib/gitlab-shell.rb代码,初始化一个GitlabShell,并且执行exec,而exec里面有几个关键步骤:

def exec(origin_cmd)
  unless origin_cmd
    puts "Welcome to GitLab, #{username}!"
    return true
  end

  args = Shellwords.shellwords(origin_cmd)
  args = parse_cmd(args)

  if GIT_COMMANDS.include?(args.first)
    GitlabMetrics.measure('verify-access') { verify_access }
  end

  process_cmd(args)

  true
rescue something #异常
end
1. 解析命令 parse_cmd

主要是处理Windows/Linux命令差异、屏蔽非法命令、LFS命令。

2. 验证权限 verify_access
/api/v4/internal/allowed

通过Rails的HTTP API :/api/v4/internal/allowed发送查询参数到Rails,接口返回此用户对这个仓库是否有此操作的权限。

参数:

{
  command => git命令
  repo => 仓库信息
  key_id => SSH key id(在数据库能找查找到对应的用户)
  protocol => ssh/env
}
3. 处理命令 process_cmd

处理命令,检测gitaly此特性是否有开启,如果开启则调用gitaly处理,否则则调用git原生命令。

设定环境变量,然后使用Kernel.exec调用目标进程替代当前进程。

env = {
    'HOME' => ENV['HOME'],
    'PATH' => ENV['PATH'],
    'LD_LIBRARY_PATH' => ENV['LD_LIBRARY_PATH'],
    'LANG' => ENV['LANG'],
    'GL_ID' => @key_id,
    'GL_PROTOCOL' => GL_PROTOCOL,
    'GL_REPOSITORY' => @gl_repository,
    'GL_USERNAME' => @username
}
# ...
Kernel.exec(env, *args, unsetenv_others: true, chdir: ROOT_PATH)

处理Git命令

以Pull,且调用Gitaly为例

// bin/gitaly-upload-pack
code, err := handler.UploadPack(os.Args[1], &request)
// go/internal/handler/upload_pack.go
func UploadPack(gitalyAddress string, request *pb.SSHUploadPackRequest) (int32, error) {
    # ...

    conn, err := client.Dial(gitalyAddress, dialOpts())
    if err != nil {
        return 0, err
    }
    defer conn.Close()

    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()
    return client.UploadPack(ctx, conn, os.Stdin, os.Stdout, os.Stderr, request)
}
// go/vendor/gitlab.com/gitlab-org/gitaly/client/upload_pack.go
func UploadPack(ctx context.Context, conn *grpc.ClientConn, stdin io.Reader, stdout, stderr io.Writer, req *pb.SSHUploadPackRequest) (int32, error) {
    ctx2, cancel := context.WithCancel(ctx)
    defer cancel()

    ssh := pb.NewSSHServiceClient(conn)
    stream, err := ssh.SSHUploadPack(ctx2)
    if err != nil {
        return 0, err
    }

    if err = stream.Send(req); err != nil {
        return 0, err
    }

    inWriter := streamio.NewWriter(func(p []byte) error {
        return stream.Send(&pb.SSHUploadPackRequest{Stdin: p})
    })

    return streamHandler(func() (stdoutStderrResponse, error) {
        return smHandler(func() (stdoutStderrResponse, error) {
        return stream.Recv()
    }, func(errC chan error) {
        _, errRecv := io.Copy(inWriter, stdin)
        stream.CloseSend()
        errC <- errRecv
    }, stdout, stderr)
}

可以看到通过grpc跟gitaly server通信,获得响应之后:

# go/vendor/gitlab.com/gitlab-org/gitaly/client/std_stream.go
exited code => resp.GetExitStatus().GetValue()
stderr => stderr.Write(resp.GetStderr())
stdout => stdout.Write(resp.GetStdout())

git客户端将标准错误打印到控制台,解析标准输出作为git数据:通过远程ssh调用命令将数据打印到标准输出传输到客户端解析

Cloning into 'gitlab-shell'...
remote: Counting objects: 5558, done.
remote: Compressing objects: 100% (2548/2548), done.
remote: Total 5558 (delta 3051), reused 5117 (delta 2754)
Receiving objects: 100% (5558/5558), 2.83 MiB | 2.72 MiB/s, done.
Resolving deltas: 100% (3051/3051), done.

Refs

2018-07-02 01:03