Shiloh/githaven
Shiloh/githaven
1
0
Fork 1
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
a077c9d551
githaven/docs/content/doc/usage/command-line.en-us.md
ngourdon a618df8d84 Add CLI commands to manage LDAP authentication source (#6681) 
* add CLI commands to manage LDAP authentication source

* delete Gogs copyright

* remove unused return value of func parseLoginSource

* fix comment

Co-Authored-By: ngourdon <31291059+ngourdon@users.noreply.github.com>

* remove config flag already present in global flags

* remove config flag from ldap commands in docs

* remove config flag handling
2019-06-17 14:32:20 -04:00

16 KiB
Raw Blame History

date title slug weight toc draft menu
2017-01-01T16:00:00+02:00 Usage: Command Line command-line 10 true false
sidebar
parent name weight identifier
usage Command Line 10 command-line

Command Line

Usage

gitea [global options] command [command or global options] [arguments...]

Global options

All global options can be placed at the command level.

  • --help, -h: Show help text and exit. Optional.
  • --version, -v: Show version and exit. Optional. (example: Gitea version 1.1.0+218-g7b907ed built with: bindata, sqlite).
  • --custom-path path, -C path: Location of the Gitea custom folder. Optional. (default: AppWorkPath/custom or $GITEA_CUSTOM).
  • --config path, -c path: Gitea configuration file path. Optional. (default: custom/conf/app.ini).
  • --work-path path, -w path: Gitea AppWorkPath. Optional. (default: LOCATION_OF_GITEA_BINARY or $GITEA_WORK_DIR)

NB: The defaults custom-path, config and work-path can also be changed at build time (if preferred).

Commands

web

Starts the server:

  • Options:
    • --port number, -p number: Port number. Optional. (default: 3000). Overrides configuration file.
    • --pid path, -P path: Pidfile path. Optional.
  • Examples:
    • gitea web
    • gitea web --port 80
    • gitea web --config /etc/gitea.ini --pid /var/run/gitea.pid
  • Notes:
    • Gitea should not be run as root. To bind to a port below 1000, you can use setcap on Linux: sudo setcap 'cap_net_bind_service=+ep' /path/to/gitea. This will need to be redone every time you update Gitea.

admin

Admin operations:

  • Commands:
    • create-user
      • Options:
        • --name value: Username. Required. As of gitea 1.9.0, use the --username flag instead.
        • --username value: Username. Required. New in gitea 1.9.0.
        • --password value: Password. Required.
        • --email value: Email. Required.
        • --admin: If provided, this makes the user an admin. Optional.
        • --access-token: If provided, an access token will be created for the user. Optional. (default: false).
        • --must-change-password: If provided, the created user will be required to choose a newer password after the initial login. Optional. (default: true).
        • --random-password: If provided, a randomly generated password will be used as the password of the created user. The value of --password will be discarded. Optional.
        • --random-password-length: If provided, it will be used to configure the length of the randomly generated password. Optional. (default: 12)
      • Examples:
        • gitea admin create-user --username myname --password asecurepassword --email me@example.com
    • change-password
      • Options:
        • --username value, -u value: Username. Required.
        • --password value, -p value: New password. Required.
      • Examples:
        • gitea admin change-password --username myname --password asecurepassword
    • regenerate
      • Options:
        • hooks: Regenerate git-hooks for all repositories
        • keys: Regenerate authorized_keys file
      • Examples:
        • gitea admin regenerate hooks
        • gitea admin regenerate keys
    • auth:
      • list:
        • Description: lists all external authentication sources that exist
        • Examples:
          • gitea admin auth list
      • delete:
        • Options:
          • --id: ID of source to be deleted. Required.
        • Examples:
          • gitea admin auth delete --id 1
      • add-oauth:
        • Options:
          • --name: Application Name.
          • --provider: OAuth2 Provider.
          • --key: Client ID (Key).
          • --secret: Client Secret.
          • --auto-discover-url: OpenID Connect Auto Discovery URL (only required when using OpenID Connect as provider).
          • --use-custom-urls: Use custom URLs for GitLab/GitHub OAuth endpoints.
          • --custom-auth-url: Use a custom Authorization URL (option for GitLab/GitHub).
          • --custom-token-url: Use a custom Token URL (option for GitLab/GitHub).
          • --custom-profile-url: Use a custom Profile URL (option for GitLab/GitHub).
          • --custom-email-url: Use a custom Email URL (option for GitHub).
        • Examples:
          • gitea admin auth add-oauth --name external-github --provider github --key OBTAIN_FROM_SOURCE --secret OBTAIN_FROM_SOURCE
      • update-oauth:
        • Options:
          • --id: ID of source to be updated. Required.
          • --name: Application Name.
          • --provider: OAuth2 Provider.
          • --key: Client ID (Key).
          • --secret: Client Secret.
          • --auto-discover-url: OpenID Connect Auto Discovery URL (only required when using OpenID Connect as provider).
          • --use-custom-urls: Use custom URLs for GitLab/GitHub OAuth endpoints.
          • --custom-auth-url: Use a custom Authorization URL (option for GitLab/GitHub).
          • --custom-token-url: Use a custom Token URL (option for GitLab/GitHub).
          • --custom-profile-url: Use a custom Profile URL (option for GitLab/GitHub).
          • --custom-email-url: Use a custom Email URL (option for GitHub).
        • Examples:
          • gitea admin auth update-oauth --id 1 --name external-github-updated
      • add-ldap: Add new LDAP (via Bind DN) authentication source
        • Options:
          • --name value: Authentication name. Required.
          • --not-active: Deactivate the authentication source.
          • --security-protocol value: Security protocol name. Required.
          • --skip-tls-verify: Disable TLS verification.
          • --host value: The address where the LDAP server can be reached. Required.
          • --port value: The port to use when connecting to the LDAP server. Required.
          • --user-search-base value: The LDAP base at which user accounts will be searched for. Required.
          • --user-filter value: An LDAP filter declaring how to find the user record that is attempting to authenticate. Required.
          • --admin-filter value: An LDAP filter specifying if a user should be given administrator privileges.
          • --username-attribute value: The attribute of the user’s LDAP record containing the user name.
          • --firstname-attribute value: The attribute of the user’s LDAP record containing the user’s first name.
          • --surname-attribute value: The attribute of the user’s LDAP record containing the user’s surname.
          • --email-attribute value: The attribute of the user’s LDAP record containing the user’s email address. Required.
          • --public-ssh-key-attribute value: The attribute of the user’s LDAP record containing the user’s public ssh key.
          • --bind-dn value: The DN to bind to the LDAP server with when searching for the user.
          • --bind-password value: The password for the Bind DN, if any.
          • --attributes-in-bind: Fetch attributes in bind DN context.
          • --synchronize-users: Enable user synchronization.
          • --page-size value: Search page size.
        • Examples:
          • gitea admin auth add-ldap --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-search-base "ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(uid=%s))" --email-attribute mail
      • update-ldap: Update existing LDAP (via Bind DN) authentication source
        • Options:
          • --id value: ID of authentication source. Required.
          • --name value: Authentication name.
          • --not-active: Deactivate the authentication source.
          • --security-protocol value: Security protocol name.
          • --skip-tls-verify: Disable TLS verification.
          • --host value: The address where the LDAP server can be reached.
          • --port value: The port to use when connecting to the LDAP server.
          • --user-search-base value: The LDAP base at which user accounts will be searched for.
          • --user-filter value: An LDAP filter declaring how to find the user record that is attempting to authenticate.
          • --admin-filter value: An LDAP filter specifying if a user should be given administrator privileges.
          • --username-attribute value: The attribute of the user’s LDAP record containing the user name.
          • --firstname-attribute value: The attribute of the user’s LDAP record containing the user’s first name.
          • --surname-attribute value: The attribute of the user’s LDAP record containing the user’s surname.
          • --email-attribute value: The attribute of the user’s LDAP record containing the user’s email address.
          • --public-ssh-key-attribute value: The attribute of the user’s LDAP record containing the user’s public ssh key.
          • --bind-dn value: The DN to bind to the LDAP server with when searching for the user.
          • --bind-password value: The password for the Bind DN, if any.
          • --attributes-in-bind: Fetch attributes in bind DN context.
          • --synchronize-users: Enable user synchronization.
          • --page-size value: Search page size.
        • Examples:
          • gitea admin auth update-ldap --id 1 --name "my ldap auth source"
          • gitea admin auth update-ldap --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn
      • add-ldap-simple: Add new LDAP (simple auth) authentication source
        • Options:
          • --name value: Authentication name. Required.
          • --not-active: Deactivate the authentication source.
          • --security-protocol value: Security protocol name. Required.
          • --skip-tls-verify: Disable TLS verification.
          • --host value: The address where the LDAP server can be reached. Required.
          • --port value: The port to use when connecting to the LDAP server. Required.
          • --user-search-base value: The LDAP base at which user accounts will be searched for.
          • --user-filter value: An LDAP filter declaring how to find the user record that is attempting to authenticate. Required.
          • --admin-filter value: An LDAP filter specifying if a user should be given administrator privileges.
          • --username-attribute value: The attribute of the user’s LDAP record containing the user name.
          • --firstname-attribute value: The attribute of the user’s LDAP record containing the user’s first name.
          • --surname-attribute value: The attribute of the user’s LDAP record containing the user’s surname.
          • --email-attribute value: The attribute of the user’s LDAP record containing the user’s email address. Required.
          • --public-ssh-key-attribute value: The attribute of the user’s LDAP record containing the user’s public ssh key.
          • --user-dn value: The user’s DN. Required.
        • Examples:
          • gitea admin auth add-ldap-simple --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-dn "cn=%s,ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(cn=%s))" --email-attribute mail
      • update-ldap-simple: Update existing LDAP (simple auth) authentication source
        • Options:
          • --id value: ID of authentication source. Required.
          • --name value: Authentication name.
          • --not-active: Deactivate the authentication source.
          • --security-protocol value: Security protocol name.
          • --skip-tls-verify: Disable TLS verification.
          • --host value: The address where the LDAP server can be reached.
          • --port value: The port to use when connecting to the LDAP server.
          • --user-search-base value: The LDAP base at which user accounts will be searched for.
          • --user-filter value: An LDAP filter declaring how to find the user record that is attempting to authenticate.
          • --admin-filter value: An LDAP filter specifying if a user should be given administrator privileges.
          • --username-attribute value: The attribute of the user’s LDAP record containing the user name.
          • --firstname-attribute value: The attribute of the user’s LDAP record containing the user’s first name.
          • --surname-attribute value: The attribute of the user’s LDAP record containing the user’s surname.
          • --email-attribute value: The attribute of the user’s LDAP record containing the user’s email address.
          • --public-ssh-key-attribute value: The attribute of the user’s LDAP record containing the user’s public ssh key.
          • --user-dn value: The user’s DN.
        • Examples:
          • gitea admin auth update-ldap-simple --id 1 --name "my ldap auth source"
          • gitea admin auth update-ldap-simple --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn

cert

Generates a self-signed SSL certificate. Outputs to cert.pem and key.pem in the current directory and will overwrite any existing files.

  • Options:
    • --host value: Comma seperated hostnames and ips which this certificate is valid for. Wildcards are supported. Required.
    • --ecdsa-curve value: ECDSA curve to use to generate a key. Optional. Valid options are P224, P256, P384, P521.
    • --rsa-bits value: Size of RSA key to generate. Optional. Ignored if --ecdsa-curve is set. (default: 2048).
    • --start-date value: Creation date. Optional. (format: Jan 1 15:04:05 2011).
    • --duration value: Duration which the certificate is valid for. Optional. (default: 8760h0m0s)
    • --ca: If provided, this cert generates it's own certificate authority. Optional.
  • Examples:
    • gitea cert --host git.example.com,example.com,www.example.com --ca

dump

Dumps all files and databases into a zip file. Outputs into a file like gitea-dump-1482906742.zip in the current directory.

  • Options:
    • --file name, -f name: Name of the dump file with will be created. Optional. (default: gitea-dump-[timestamp].zip).
    • --tempdir path, -t path: Path to the temporary directory used. Optional. (default: /tmp).
    • --skip-repository, -R: Skip the repository dumping. Optional.
    • --database, -d: Specify the database SQL syntax. Optional.
    • --verbose, -V: If provided, shows additional details. Optional.
  • Examples:
    • gitea dump
    • gitea dump --verbose

generate

Generates random values and tokens for usage in configuration file. Useful for generating values for automatic deployments.

  • Commands:
    • secret:
      • Options:
        • INTERNAL_TOKEN: Token used for an internal API call authentication.
        • JWT_SECRET: LFS & OAUTH2 JWT authentication secret (LFS_JWT_SECRET is aliased to this option for backwards compatibility).
        • SECRET_KEY: Global secret key.
      • Examples:
        • gitea generate secret INTERNAL_TOKEN
        • gitea generate secret JWT_SECRET
        • gitea generate secret SECRET_KEY

keys

Provides an SSHD AuthorizedKeysCommand. Needs to be configured in the sshd config file:

...
# The value of -e and the AuthorizedKeysCommandUser should match the
# username running gitea
AuthorizedKeysCommandUser git
AuthorizedKeysCommand /path/to/gitea keys -e git -u %u -t %t -k %k

The command will return the appropriate authorized_keys line for the provided key. You should also set the value SSH_CREATE_AUTHORIZED_KEYS_FILE=false in the [server] section of app.ini.

NB: opensshd requires the gitea program to be owned by root and not writable by group or others. The program must be specified by an absolute path.