README.txt
349 lines
| 11.3 KiB
| text/plain
|
TextLexer
Marcin Kasperski
|
r164 | .. -*- mode: rst; compile-command: "rst2html README.txt README.html" -*- | ||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r191 | ======================================================= | ||
Marcin Kasperski
|
r181 | Mercurial Keyring | ||
Marcin Kasperski
|
r191 | ======================================================= | ||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r181 | Mercurial Keyring is a Mercurial_ extension used to securely save HTTP | ||
and SMTP authentication passwords in password databases (Gnome | ||||
Keyring, KDE KWallet, OSXKeyChain, Windows Vault etc). | ||||
With ``mercurial_keyring`` active, Mercurial remembers your passwords | ||||
and reuses them without prompting (as if you stored them in ``.hgrc``), | ||||
but password storage is reasonably secure. | ||||
Actual password storage is implemented by the keyring_ library, this | ||||
extension glues it to Mercurial. | ||||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r190 | .. contents:: | ||
:local: | ||||
:depth: 2 | ||||
.. sectnum:: | ||||
Marcin Kasperski
|
r35 | .. _keyring: http://pypi.python.org/pypi/keyring | ||
Marcin Kasperski
|
r36 | .. _Mercurial: http://mercurial.selenic.com | ||
Marcin Kasperski
|
r35 | |||
How does it work | ||||
Marcin Kasperski
|
r191 | ======================================================= | ||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r181 | On your first pull or push to HTTP url (or first email sent via given | ||
SMTP server), you are prompted for the password, just like bare | ||||
Mercurial does. But the password you entered is saved to appropriate | ||||
password database. On successive runs, whenever the password is | ||||
needed, ``mercurial_keyring`` checks for password in password | ||||
database, and uses it without troubling you. | ||||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r181 | In case password turns out to be incorrect (for example, because you | ||
Marcin Kasperski
|
r191 | changed it, or entered it incorrectly), ``mercurial_keyring`` prompts | ||
you again, and overwrites the password. | ||||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r181 | You can use many passwords (for various remote urls). Saved passwords | ||
are identified by pair of username and url prefix. See below for | ||||
information how to configure those properly. | ||||
Marcin Kasperski
|
r37 | |||
Marcin Kasperski
|
r35 | Installation | ||
Marcin Kasperski
|
r191 | ======================================================= | ||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r36 | Prerequisites | ||
------------- | ||||
Marcin Kasperski
|
r164 | This extension requires keyring_ and `mercurial_extension_utils`_ to | ||
work. In many cases both will be installed automatically while you | ||||
Marcin Kasperski
|
r182 | install ``mercurial_keyring``, but you may need to control the process. | ||
Marcin Kasperski
|
r164 | |||
The keyring_ library can usually be installed by:: | ||||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r164 | pip install --user keyring | ||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r164 | (or ``easy_install keyring``), but on some systems it is preferable to | ||
use official distribution archive. For example, on Debian and Ubuntu, | ||||
you may install ``python-keyring`` and either ``python-keyring-gnome`` | ||||
or ``python-keyring-kwallet`` packages:: | ||||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r164 | sudo apt-get install python-keyring python-keyring-gnome | ||
(this will save you the need to provide working compiler and various | ||||
development libraries). | ||||
Marcin Kasperski
|
r36 | |||
Marcin Kasperski
|
r164 | The `mercurial_extension_utils`_ module is tiny Python-only module, | ||
which can be installed by:: | ||||
Marcin Kasperski
|
r57 | |||
Marcin Kasperski
|
r164 | pip install --user mercurial_extension_utils | ||
Marcin Kasperski
|
r215 | but in some cases (Windows…) requires more care. See | ||
Marcin Kasperski
|
r180 | `mercurial_extension_utils`_ documentation. | ||
Marcin Kasperski
|
r164 | |||
Marcin Kasperski
|
r57 | |||
Marcin Kasperski
|
r36 | Extension installation | ||
---------------------- | ||||
There are two possible ways of installing the extension: using PyPi package, | ||||
Marcin Kasperski
|
r164 | or using source clone. | ||
Marcin Kasperski
|
r36 | |||
Marcin Kasperski
|
r164 | To install as a package:: | ||
Marcin Kasperski
|
r36 | |||
Marcin Kasperski
|
r164 | pip install --user mercurial_keyring | ||
Marcin Kasperski
|
r36 | |||
Marcin Kasperski
|
r164 | (or ``sudo pip install mercurial_keyring`` for system-wide | ||
installation) and then enable it in ``~/.hgrc`` (or | ||||
``/etc/mercurial/hgrc`` or ``Mercurial.ini``) using:: | ||||
Marcin Kasperski
|
r36 | |||
[extensions] | ||||
mercurial_keyring = | ||||
Marcin Kasperski
|
r215 | To install using source clone, install keyring_ according to the | ||
instructions above, then clone:: | ||||
Marcin Kasperski
|
r164 | |||
hg clone https://bitbucket.org/Mekk/mercurial_keyring/ | ||||
hg clone https://bitbucket.org/Mekk/mercurial-extension_utils/ | ||||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r215 | and configure Mercurial using full path to the extension module:: | ||
Marcin Kasperski
|
r35 | |||
[extensions] | ||||
Marcin Kasperski
|
r164 | mercurial_keyring = /path/to/mercurial_keyring/mercurial_keyring.py | ||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r37 | .. _the code: | ||
.. _mercurial_keyring.py: http://bitbucket.org/Mekk/mercurial_keyring/src/tip/mercurial_keyring.py | ||||
Marcin Kasperski
|
r35 | Password backend configuration | ||
Marcin Kasperski
|
r191 | ======================================================= | ||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r215 | The most appropriate password backend should usually be picked without | ||
configuration (considering installed libraries, operating system, | ||||
active desktop session). Still, if necessary, it can be configured | ||||
using ``keyringrc.cfg`` file. Refer to keyring_ docs for more | ||||
details. | ||||
Marcin Kasperski
|
r180 | |||
.. note:: | ||||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r180 | With current (as I write) keyring (5.6), this file is (on Linux) | ||
located at ``~/.local/share/python_keyring/keyringrc.cfg`` and | ||||
Marcin Kasperski
|
r215 | it's example content looks like:: | ||
Marcin Kasperski
|
r180 | |||
[backend] | ||||
default-keyring=keyring.backends.Gnome.Keyring | ||||
# default-keyring=keyring.backends.kwallet.Keyring | ||||
For list of known backends run ``pydoc keyring.backends``. | ||||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r181 | ``hgrc`` configuration (HTTP) | ||
Marcin Kasperski
|
r191 | ======================================================= | ||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r181 | Mercurial Keyring uses standard Mercurial ``[auth]`` configuration to | ||
detect your username (on given remote) and url prefix. You are | ||||
strongly advised to configure both. | ||||
Without the username ``mercurial_keyring`` can't save or restore | ||||
passwords, so it disables itself. | ||||
Without url prefix ``mercurial_keyring`` works, but binds passwords to | ||||
repository urls. That means you will have to (re)enter password for | ||||
every repository cloned from given remote (and that there will be many | ||||
copies of this password in secure storage). | ||||
Repository level configuration | ||||
------------------------------------ | ||||
Marcin Kasperski
|
r35 | Edit repository-local ``.hg/hgrc`` and save there the remote | ||
repository path and the username, but do not save the password. For | ||||
example: | ||||
:: | ||||
[paths] | ||||
myremote = https://my.server.com/hgrepo/someproject | ||||
[auth] | ||||
Marcin Kasperski
|
r181 | myremote.prefix = https://my.server.com/hgrepo | ||
myremote.username = John | ||||
Marcin Kasperski
|
r35 | |||
Simpler form with url-embedded name can also be used: | ||||
:: | ||||
[paths] | ||||
Marcin Kasperski
|
r181 | bitbucket = https://John@my.server.com/hgrepo/someproject/ | ||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r202 | but is not recommended. | ||
Marcin Kasperski
|
r181 | Note that all repositories sharing the same ``prefix`` share the same | ||
password. | ||||
Marcin Kasperski
|
r46 | |||
Marcin Kasperski
|
r181 | Mercurial allows also for password in ``.hg/hgrc`` (either given by | ||
``«prefix».password``, or embedded in url). If such password is found, | ||||
Marcin Kasperski
|
r182 | Mercurial Keyring disables itself. | ||
Marcin Kasperski
|
r181 | |||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r181 | Account-level configuration | ||
--------------------------- | ||||
If you are consistent about remote repository nicknames, you can | ||||
configure the username in your `~/.hgrc` (`.hgrc` in your home | ||||
directory). For example, write there:: | ||||
Marcin Kasperski
|
r53 | |||
[auth] | ||||
acme.prefix = hg.acme.com/repositories | ||||
acme.username = johnny | ||||
acme.schemes = http https | ||||
Marcin Kasperski
|
r181 | bitbucket.prefix = https://bitbucket.org | ||
bitbucket.username = Mekk | ||||
mydep.prefix = https://dev.acmeorg.com | ||||
mydep.username = drmartin | ||||
Marcin Kasperski
|
r53 | |||
Marcin Kasperski
|
r215 | and as long as you use ``acme`` alias for repositories like | ||
Marcin Kasperski
|
r182 | ``https://hg.acme.com/repositories/my_beautiful_app``, username | ||
``johnny`` will be used, and the same password reused. Similarly | ||||
Marcin Kasperski
|
r181 | any ``hg push bitbucket`` will share the same password. | ||
With such config repository-level ``.hg/hgrc`` need only contain | ||||
``[paths]``. | ||||
Additional advantage of this method is that it works also during | ||||
`clone`. | ||||
.. note:: | ||||
Marcin Kasperski
|
r53 | |||
Marcin Kasperski
|
r215 | Mercurial Keyring works well with `Path Pattern`_. On my setup I use | ||
prefix as above, and:: | ||||
Marcin Kasperski
|
r53 | |||
Marcin Kasperski
|
r181 | [path_pattern] | ||
bitbucket.local = ~/devel/{below} | ||||
bitbucket.remote = https://bitbucket.org/Mekk/{below:/=-} | ||||
so all my repositories understand ``hg push bitbucket`` without | ||||
any repository-level configuration. | ||||
``hgrc`` configuration (SMTP) | ||||
Marcin Kasperski
|
r191 | ======================================================= | ||
Marcin Kasperski
|
r35 | |||
Edit either repository-local ``.hg/hgrc``, or ``~/.hgrc`` and set | ||||
Marcin Kasperski
|
r37 | there all standard email and smtp properties, including SMTP | ||
username, but without SMTP password. For example: | ||||
Marcin Kasperski
|
r35 | |||
:: | ||||
[email] | ||||
method = smtp | ||||
from = Joe Doe <Joe.Doe@remote.com> | ||||
[smtp] | ||||
host = smtp.gmail.com | ||||
port = 587 | ||||
username = JoeDoe@gmail.com | ||||
tls = true | ||||
Marcin Kasperski
|
r37 | Just as in case of HTTP, you *must* set username, but *must not* set | ||
password here to use the extension, in other cases it will revert to | ||||
the default behavior. | ||||
Marcin Kasperski
|
r35 | |||
Usage | ||||
Marcin Kasperski
|
r191 | ====================================================== | ||
Saving and restoring passwords | ||||
------------------------------------------------------- | ||||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r36 | Configure the repository as above, then just ``hg pull``, ``hg push``, | ||
etc. You should be asked for the password only once (per every | ||||
Marcin Kasperski
|
r46 | username and remote repository prefix or url combination). | ||
Marcin Kasperski
|
r36 | Similarly, for email, configure as above and just ``hg email``. | ||
Marcin Kasperski
|
r46 | Again, you will be asked for the password once (per every username and | ||
email server address combination). | ||||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r191 | Checking password status (``hg keyring_check``) | ||
------------------------------------------------------- | ||||
The ``keyring_check`` command can be used to check whether/which | ||||
password(s) are saved. It can be used in three ways: | ||||
- without parameters, it prints info related to all HTTP paths | ||||
defined for current repository (everything from ``hg paths`` | ||||
that resolves to HTTP url):: | ||||
hg keyring_check | ||||
- given alias as param, it prints info about this alias:: | ||||
hg keyring_check work | ||||
- finally, any path can be checked:: | ||||
hg keyring_check https://bitbucket.org/Mekk/mercurial_keyring | ||||
Deleting saved password (``hg keyring_clear``) | ||||
------------------------------------------------------- | ||||
The ``keyring_clear`` command removes saved password related to given | ||||
path. It can be used in two ways: | ||||
- given alias as param, it drops password used by this alias:: | ||||
hg keyring_clear work | ||||
- given full path, it drops password related to this path:: | ||||
hg keyring_clear https://bitbucket.org/Mekk/mercurial_keyring | ||||
Marcin Kasperski
|
r215 | Managing passwords using GUI tools | ||
------------------------------------------------------ | ||||
Many password backends provide GUI tools for password management, | ||||
for example Gnome Keyring passwords can be managed using ``seahorse``, | ||||
and KDE Wallet using ``kwalletmanager``. Those GUI tools can be used | ||||
to review, edit, or delete saved passwords. | ||||
Unfortunately, as I write, keyring_ library does not allow one to | ||||
configure how/where exactly saved passwords are put in the hierarchy, | ||||
and the place is not always intuitive. For example, in KDE Wallet, all | ||||
passwords saved using ``mercurial_keyring`` show up in the folder | ||||
named ``Python``. | ||||
.. note:: | ||||
This is slightly problematic in case ``mercurial_keyring`` is not | ||||
the only program using keyring_ library. Passwords saved by another | ||||
Python application or script (which also uses keyring_) will be put | ||||
into the same place, and it may be unclear which password belongs | ||||
to which program. To remedy this, ``mercurial_keyring`` applies | ||||
slightly unusual labels of the form | ||||
Marcin Kasperski
|
r216 | ``«username»@@«urlprefix»@Mercurial`` - for example my bitbucket | ||
password is labelled ``Mekk@@https://bitbucket.org@Mercurial``. | ||||
Marcin Kasperski
|
r215 | |||
Marcin Kasperski
|
r35 | Implementation details | ||
Marcin Kasperski
|
r191 | ======================================================= | ||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r36 | The extension is monkey-patching the mercurial ``passwordmgr`` class | ||
Marcin Kasperski
|
r182 | to replace the ``find_user_password`` method. Detailed order of operations | ||
Marcin Kasperski
|
r37 | is described in the comments inside `the code`_. | ||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r155 | History | ||
Marcin Kasperski
|
r191 | ======================================================= | ||
Marcin Kasperski
|
r155 | |||
See `HISTORY.txt`_. | ||||
Marcin Kasperski
|
r35 | Development | ||
Marcin Kasperski
|
r191 | ======================================================= | ||
Marcin Kasperski
|
r35 | |||
Marcin Kasperski
|
r36 | Development is tracked on BitBucket, see | ||
http://bitbucket.org/Mekk/mercurial_keyring/ | ||||
Marcin Kasperski
|
r35 | |||
Additional notes | ||||
Marcin Kasperski
|
r191 | ======================================================= | ||
Marcin Kasperski
|
r35 | |||
Information about this extension is also available | ||||
Marcin Kasperski
|
r36 | on Mercurial Wiki: http://mercurial.selenic.com/wiki/KeyringExtension | ||
Marcin Kasperski
|
r155 | |||
Marcin Kasperski
|
r195 | Check also `other Mercurial extensions I wrote`_. | ||
.. _other Mercurial extensions I wrote: http://mekk.bitbucket.org/mercurial.html | ||||
Marcin Kasperski
|
r157 | .. _HISTORY.txt: http://bitbucket.org/Mekk/mercurial_keyring/src/tip/HISTORY.txt | ||
Marcin Kasperski
|
r164 | .. _TortoiseHg: http://tortoisehg.bitbucket.org/ | ||
.. _Mercurial: http://mercurial.selenic.com | ||||
.. _mercurial_extension_utils: https://bitbucket.org/Mekk/mercurial-extension_utils/ | ||||
Marcin Kasperski
|
r181 | .. _Path Pattern: https://bitbucket.org/Mekk/mercurial-path_pattern/ | ||