gitauth 0.0.5.0

data/README.rdoc

@@ -0,0 +1,141 @@
+== GitAuth - SSH-based authentication for Shared Git Repositories.
+
+If you've heard of Gitosis before, GitAuth is like Gitosis but A) in Ruby, B) slightly simpler to get going and C) doesn't use a git repository to manage users.
+
+At the moment configuration / adding users is done via a single command - +gitauth+. For usage, see below.
+
+=== License
+
+GitAuth is licensed under AGPL, with parts of the code being derived
+from Gitorius - http://gitorious.org
+
+=== Installing GitAuth
+
+Getting started is relatively simple. First of, you'll need to log onto the remote server / your git host. Next, you'll need to install the gem:
+
+  sudo gem install brownbeagle-gitauth --source http://gems.github.com/
+  
+Or, if you want to avoid the gems approach, you can use simply clone the repository
+as follows and use the git submodule setup in order to vendor rack, sinatra and perennial:
+
+  git clone git://github.com/brownbeagle/gitauth.git
+  cd gitauth
+  git submodule init
+  git submodule update
+  
+With the gitauth binary being in the bin folder.
+  
+Once that's done, the +gitauth+ and +gitauth-shell+ commands should be in your path.
+Next, you'll want to (in most cases anyway) use a specific +git+ user to host repositories.
+
+Using the example of ubuntu, we'll add a git user under which all actions will now take place (note, this is essentially the same as gitosis):
+
+  sudo adduser --disabled-password --shell /bin/bash --group --home /home/git --system --gecos 'gitauth user for version control' git
+  
+Now, whenever you run the +gitauth+ executable, you'll do so as the user you just created
+above. For example purposes, I suggest using the following in order to run all commands
+as the 'git' user:
+
+  sudo -H -u git -i
+  
+And finally, to create a settings file and initialize .ssh and authorized_keys, perform the
+following:
+
+  gitauth install
+  
+Note that when it asks you for the gitauth shell path, the default will lock
+it to the current gitauth version SO if you want it to stay up to date between gem versions
+point it to the path for always-current executable (e.g. on Ubuntu 9.04 w/ apt-get ruby + gems,
++/var/lib/gems/1.8/bin/gitauth-shell+)  
+
+Also, Note that if use the --admin option with path to a public key to the end of the install command,
+it will initialize a new +admin+ user who can also login via SSH. e.g.
+
+  gitauth install --admin id_rsa.pub
+  
+Would initialize an admin user with the given public key.
+
+Note that from now on, all gitauth keys should be run either logged in as
+git (via the admin user and ssh) or by being prefixed with asgit or "sudo -H -u git"
+
+=== Web Interface
+
+To start the web interface, just run:
+
+  gitauth web-app
+  
+The first time you boot the web app, you will be prompted
+to enter a username and a password. Please do so
+and then surf to http://your-server-ip:8998/
+
+For people running passenger, you can simply point it at
+the public subdirectory and it will act as any normal passenger
+web app. It's worth noting that in this approach you need
+to run gitauth web-app at least once to setup a username and
+password.
+
+=== Adding Users
+
+Whenever you want to add a user, it's as simple as:
+
+  gitauth add-user user-name path-to-public-key
+  
+Note that if the --admin option is specified, the user will
+be able to log in to the shell via SSH and will also be able
+to access any repository.
+
+=== Adding Repositories
+
+Adding a repository is a two step process. First, you create it:
+
+  gitauth add-repo repo-name
+  
+If you wish to initialize the repository with a blank commit (so
+git clone works straight away), simply pass --make-empty / -m as
+an option. e.g.:
+
+  gitauth add-repo repo-name --make-empty
+  
+Then, for every user who needs access, you do:
+
+  gitauth permissions repo-name user-name --type=permission-type
+  
+Where permission type is read, write or all. If permission
+type isn't specified, it will default to all. If you wish
+to remove a user from a repository, you can simply pass
+use the type as none.
+
+=== Accessing repos:
+
+Finally, once you've added users / repos, using them is as simple
+as doing the following on each users computer:
+
+  git clone git@your-remote-host:repo-name
+
+Or
+
+  git clone git@your-remote-host:repo-name.git
+  
+Either form working just as well.
+
+Note that for the first time you push, you will need
+to use the full form (as below) unless you've used
+the --make-empty / -m option when you created the repo.
+
+  git push origin master
+
+As it starts as an empty repo.
+
+Alternatively, if you get the error "fatal: no matching remote head" when you
+clone and it doesn't create a local copy, you'll instead have to do the following
+on your local PC (due to the way git handles remote repositories):
+
+  mkdir my-repo
+  cd my-repo
+  git init
+  touch README
+  git add .
+  git commit -m "Added blank readme"
+  git add remote origin git@your-server:my-repo.git
+  git push origin master
+  

data/USAGE

@@ -0,0 +1,70 @@
+GitAuth is a tool to provide authenticated git hosting from any unix like
+box using ruby, git-shell and a whole lot of awesomeness.
+
+Available commands include:
+  
+  ls-users    - Lists all users handled by GitAuth
+  
+  ls-groups   - Lists all groups handled by GitAuth
+  
+  ls-repos    - Lists all repositories handled by GitAuth
+  
+  show-user   - Shows information about a user with a given name
+    e.g: gitauth show-user darcy
+    
+  show-group  - Shows information about a group with a given name
+    e.g: gitauth show-group brownbeagle
+    or,: gitauth show-group @brownbeagle
+    
+  show-repo   - Shows information about a repository with a given name
+    e.g: gitauth show-repo project-a
+  
+  add-user    - adds a user with a specific name and ssh key
+    e.g. gitauth add-user darcy ~/id_rsa-one.pub
+    or,: gitauth add-user sutto ~/id_rsa-two.pub --admin
+    
+    Would create two users, one an admin and one a normal user.
+    
+  add-group   - Adds a group with a specified name.  
+    e.g: gitauth add-group brownbeagle
+    or,: gitauth add-group brownbeagle
+    
+    From there on in, you can refer to the group as @brownbeagle
+    
+  add-repo    - Adds a repository with a specific name and an optional path
+    e.g: gitauth add-repo project-a
+    or,: gitauth add-repo project-b --make-empty
+    or,: gitauth add-repo project-c my-path-to-repo.git
+    or,: gitauth add-repo project-d my-path-to-other-repo --make-empty
+    
+    --make-empty initializes it with a blank commit whilst
+    a second argument sets the path for the created repository.
+    The path is only ever used internally, the user refers to
+    it externally. e.g, project-c above would be accessible by:
+    user@your-server.com:project-c or user@your-server.com:project-c.git
+  
+  rm-user     - Removes a user with the given name
+    e.g: gitauth rm-user darcy
+
+  rm-group    - Removes a specific group from GitAuth
+    e.g: gitauth rm-group brownbeagle
+    or,: gitauth rm-group @brownbeagle
+
+  rm-repo     - Removes a repository from gitauth (destroys it on the filesystem as well)
+    e.g: gitauth rm-repo project-a
+    
+  permissions - Set the permissions for a given user or group on a specific repository.
+    e.g: gitauth permissions project-a darcy
+    or,: gitauth permissions project-b darcy --type read
+    or,: gitauth permissions project-c darcy --type none
+    or,: gitauth permissions project-a @brownbeagle -t read
+    or,: gitauth permissions project-b @brownbeagle
+    
+    The first argument being the repository name, the second a target -
+    either a user (e.g. darcy), or, if prefixed with an @-symbol, a group.
+    An optional --type argument specifies what permissions to use (all, read, write
+    or none - defaulting to all).
+    
+  web-app     - Starts up the web app, serving on port 8998
+    e.g: gitauth web-app
+

data/bin/gitauth

@@ -0,0 +1,261 @@
+#!/usr/bin/env ruby
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "lib", "gitauth"))
+
+GitAuth::Application.processing(ARGV) do |a|
+  a.banner = "GitAuth v#{GitAuth.version}"
+  
+  a.generator!
+  
+  a.option(:force, "force the creation of the settings file")
+  a.option(:admin, "pass the path to a ssh public key and it adds a default admin user")
+  a.add("install", "Sets up GitAuth for the current user") do |options|
+    
+    setup_generator ".", :silent => true
+    
+    # Check for a valid admin key
+    if options.has_key?(:admin) && (!options[:admin].is_a?(String) || !file?(options[:admin]))
+      puts "You provided the admin option but didn't provide it with a path to public key."
+      die! "Please re-run again with a path to a key, e.g. --admin=~/id_rsa.pub"
+    end
+    
+    if !yes?("Are you logged in as the correct user?")
+      die!("Please log in as the correct user and re-run") 
+    end
+
+    if !GitAuth.has_git?
+      die!("'git' was not found in your path - please install it / add it to your path before continuing.")
+    end
+
+    ssh_folder = "~/.ssh"
+    if !folder?(ssh_folder)
+      folders ssh_folder
+      chmod 0700, ssh_folder
+    end
+
+    authorized_keys = ssh_folder / "authorized_keys"
+    if !file?(authorized_keys)
+      file authorized_keys, "\n\n## GitAuth - DO NO EDIT BELOW THIS LINE ##\n"
+      chmod 0600, authorized_keys
+    end
+
+    gitauth_folder = "~/.gitauth/"
+    folders gitauth_folder
+
+    settings_file = gitauth_folder / "settings.yml"
+    if !file?(settings_file) || options[:force]
+      repo_path = ask("Where did you want repositories to be stored?", "~/repositories")
+      repo_path = File.expand_path(repo_path)
+      folders repo_path
+
+      default_shell_path = GitAuth::BASE_DIR.join("bin", "gitauth-shell").to_s
+      gitauth_shell_path = ""
+      gitauth_shell_set  = false
+      while gitauth_shell_path.blank? || !(file?(gitauth_shell_path) && executable?(gitauth_shell_path))
+        # A Give the user a message if the path doesn't exist.
+        if gitauth_shell_set
+          puts "The shell you provided, #{gitauth_shell_path}, isn't executable"
+        else
+          gitauth_shell_set = true
+        end
+        gitauth_shell_path = ask("What is the path to your gitauth-shell?", default_shell_path)
+        gitauth_shell_path = File.expand_path(gitauth_shell_path)
+      end
+
+      GitAuth::Settings.update!({
+        :base_path            => File.expand_path(repo_path),
+        :authorized_keys_file => File.expand_path(authorized_keys),
+        :shell_executable     => File.expand_path(gitauth_shell_path)
+      })
+    end
+
+    if options[:admin]
+      key_contents = File.read(options[:admin]).strip
+      if GitAuth::User.create("admin", true, key_contents)
+        puts "Default admin user added with key '#{options[:admin]}'"
+      else
+        die! "Error adding default admin user with key at '#{options[:admin]}'"
+      end
+    end
+    
+  end
+
+  a.controller!(:web_app, "Starts the gitauth frontend using the default sintra runner", :skip_path => true)
+  
+  a.option(:force, "Skip the verification / confirmation part of adding the permissions")
+  a.option(:type, "The type of permissions - one of all, read, write or none. Defaults to all")
+  full_desc = "Gives a specific user or group the specified permissions to a given repository"
+  a.add("permissions REPOSITORY USER-OR-GROUP", full_desc) do |repo, target, options|
+    GitAuth.prepare
+    permissions = options[:type] || 'all'
+    
+    if !%w(all read write none).include? permissions
+      die! "'#{permissions}' is not a valid permission type. It must be all, read, write or none"
+    end
+    
+    real_permissions = ({"all" => ["read", "write"], "none" => []}[permissions] || [permissions])
+    repository       = GitAuth::Repo.get(repo)
+    real_target      = GitAuth.get_user_or_group(target)
+    
+    die! "Unknown repository '#{repo}'"      if repository.blank?
+    die! "Unknown user or group '#{target}'" if real_target.blank?
+    
+    if options[:force] || yes?("Adding '#{permissions}' permissions for #{real_target} to #{repository.name}")
+      repository.update_permissions!(real_target, real_permissions)
+      puts "Permissions updated."
+    else
+      puts "Permissions not added, exiting."
+    end
+  end
+    
+  a.option(:admin, "Makes a user an admin user")
+  a.add("add-user NAME PATH-TO-PUBLIC-KEY", "Creates a user with a given public key") do |name, ssh_key, options|
+    GitAuth.prepare
+    die! "'#{ssh_key}' is not a valid path to a public key" if !File.file?(ssh_key)
+    admin = !!options[:admin]
+    contents = File.read(ssh_key).strip
+    if GitAuth::User.create(name, admin, contents)
+      puts "Successfully added user '#{name}' (user #{admin ? 'is' : 'is not'} an admin)"
+    else
+      die! "There was an unknown error attempting to add a user called '#{name}'"
+    end
+  end
+  
+  a.option(:make_empty, "Initializes the repository to be empty / have an initial blank commit")
+  a.add("add-repo NAME [PATH=NAME]", "Creates a named repository, with an optional path on the file system") do |name, *args|
+    GitAuth.prepare
+    options = args.extract_options!
+    path = (args.shift || name)
+    if (repo = GitAuth::Repo.create(name, path))
+      puts "Successfully created repository '#{name}' located at '#{path}'"
+      if options[:make_empty]
+        puts "Attempting to make empty repository"
+        repo.make_empty!
+      end
+    else
+      die! "Unable to create repository '#{name}' in location '#{path}'"
+    end
+  end
+  
+  a.add("add-group NAME", "Creates a group with a given name") do |name, options|
+    GitAuth.prepare
+    if GitAuth::Group.create(name)
+      puts "Successfully created group '#{name}'"
+    else
+      die! "Unable to create group '#{name}'"
+    end
+  end
+  
+  a.add("ls-users", "Lists all users currently managed by gitauth") do |options|
+    GitAuth.prepare
+    puts "Users:"
+    (GitAuth::User.all || []).each do |user|
+      line = "- #{user}"
+      line << " (admin)" if user.admin?
+      puts line
+    end
+  end
+  
+  a.add("ls-repos", "Lists all repositories currently managed by gitauth") do |options|
+    GitAuth.prepare
+    puts "Repositories:"
+    (GitAuth::Repo.all || []).each do |repo|
+      line = " - #{repo.name}"
+      line << " (#{repo.path})" if repo.path != repo.name
+      puts line
+    end
+  end
+  
+  a.add("ls-groups", "Lists all groups currently managed by gitauth") do |options|
+    GitAuth.prepare
+    puts "Groups:"
+    (GitAuth::Group.all || []).each do |group|
+      puts "- #{group} (#{group.members.empty? ? "no members" : group.members.join(", ")})"
+    end
+  end
+  
+  a.add("rm-user NAME", "Removes the specified user") do |name, options|
+    GitAuth.prepare
+    user = GitAuth::User.get(name)
+    die! "Unknown user '#{name}'" if user.blank?
+    user.destroy!
+    puts "Removed user '#{name}' - Please note you will manually need to remove this users line from authorized_keys"
+  end
+  
+  a.add("rm-repo NAME", "Removes the specified repo") do |name, options|
+    GitAuth.prepare
+    repo = GitAuth::Repo.get(name)
+    die! "Unknown repo '#{name}'" if repo.blank?
+    repo.destroy!
+    puts "Removed repo '#{name}'"
+  end
+  
+  a.add("rm-group NAME", "Removes the specified group") do |name, options|
+    GitAuth.prepare
+    group = GitAuth::Group.get(name)
+    die! "Unknown group '#{name}'" if group.blank?
+    group.destroy!
+    puts "Removed group '#{name}'"
+  end
+  
+  a.add("usage", "Prints out the sample usage instructions") do |options|
+    pager = nil
+    if ENV.has_key?('PAGER')
+      pager = ENV['PAGER'].blank? ? 'cat' : ENV['PAGER']
+    else
+      pager = "less"
+    end
+    exec "#{pager} '#{GitAuth::BASE_DIR.join("USAGE")}'"
+  end
+  
+  a.add("show-repo NAME", "Shows information for a repository with a given name") do |name, options|
+    GitAuth.prepare
+    repo = GitAuth::Repo.get(name)
+    die! "Unknown repository '#{repo}'" if repo.blank?
+    puts "Repository Name: #{repo.name}"
+    puts "Repository Path: #{repo.path}"
+    puts "Actual Path:     #{repo.real_path}"
+    puts "\nRead Permissions:"
+    read_perms = repo.permissions.fetch(:read, [])
+    read_perms.each { |item| puts "  - #{item}" }
+    puts "  - No read permissions" if read_perms.blank?
+    puts "\nWrite Permissions:"
+    write_perms = repo.permissions.fetch(:write, [])
+    write_perms.each { |item| puts "  - #{item}" }
+    puts "  - No write permissions" if write_perms.blank?
+  end
+  
+  a.add("show-group NAME", "Shows information for a group with a given name") do |name, options|
+    GitAuth.prepare
+    group = GitAuth::Group.get(name)
+    die! "Unable to find a group named '#{name}'" if group.blank?
+    puts "Group Name:     #{group.name}"
+    puts "Reference Name: #{group.to_s}"
+    puts "\nGroup Members:"
+    group.members.each { |member| puts "  - #{member}" }
+    puts "  - This group has no members" if group.members.blank?
+  end
+  
+  a.add("show-user NAME", "Shows details for a user with a specific name") do |name, options|
+    GitAuth.prepare
+    user = GitAuth::User.get(name)
+    die! "Unable to find a user named '#{name}'" if user.blank?
+    puts "User Name: #{user.name}"
+    groups = user.groups
+    puts "\nGroups:"
+    puts "  - This user isn't a member of any groups" if groups.blank?
+    groups.each { |g| puts "  - #{g.to_s}" }
+  end
+  
+  a.add("enable-htaccess-auth", "Generates .htaccess and .htpasswd files, disabling the built in auth") do |options|
+    die!  "Apache-based authentication is already used" if GitAuth::ApacheAuthentication.setup?
+    GitAuth::ApacheAuthentication.setup
+    puts "Apache-based authentication setup."
+  end
+  
+  a.add("disable-htaccess-auth", "Removes .htaccess and .htpasswd files, enabling the built in auth") do |options|
+    die! "Apache-based authentication is not currently used" unless GitAuth::ApacheAuthentication.setup?
+    GitAuth::ApacheAuthentication.remove
+    puts "Removed Apache-based authentication"
+  end
+  
+end