|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320 |
- ---
- date: "2017-01-01T16:00:00+02:00"
- title: "Usage: Command Line"
- slug: "command-line"
- weight: 10
- toc: true
- draft: false
- menu:
- sidebar:
- parent: "usage"
- name: "Command Line"
- weight: 10
- identifier: "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 1024, 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.
- - `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status.
- - `--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.
- - `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status.
- - `--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.
- - `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status.
- - `--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.
- - `--restricted-filter value`: An LDAP filter specifying if a user should be given restricted status.
- - `--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:
-
- ```ini
- ...
- # 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.
- NB: Gitea must be running for this command to succeed.
-
- #### migrate
- Migrates the database. This command can be used to run other commands before starting the server for the first time.
- This command is idempotent.
-
- #### convert
- Converts an existing MySQL database from utf8 to utf8mb4.
-
- #### doctor
- Diagnose the problems of current gitea instance according the given configuration.
- Currently there are a check list below:
-
- - Check if OpenSSH authorized_keys file id correct
- When your gitea instance support OpenSSH, your gitea instance binary path will be written to `authorized_keys`
- when there is any public key added or changed on your gitea instance.
- Sometimes if you moved or renamed your gitea binary when upgrade and you haven't run `Update the '.ssh/authorized_keys' file with Gitea SSH keys. (Not needed for the built-in SSH server.)` on your Admin Panel. Then all pull/push via SSH will not be work.
- This check will help you to check if it works well.
-
- For contributors, if you want to add more checks, you can wrie ad new function like `func(ctx *cli.Context) ([]string, error)` and
- append it to `doctor.go`.
-
- ```go
- var checklist = []check{
- {
- title: "Check if OpenSSH authorized_keys file id correct",
- f: runDoctorLocationMoved,
- },
- // more checks please append here
- }
- ```
-
- This function will receive a command line context and return a list of details about the problems or error.
|