Starting seahorse-agent in the Session

NOTE: This is a discussion for package maintainers and developers.

Seahorse comes with seahorse-agent, a daemon that integrates with GPG and SSH to provide proper GNOME integrated passphrase prompting and key caching.

To integrate with GPG and SSH some strange voodoo is necessary. This page attempts to explain that and how a distro can properly integrate and start seahorse-agent when the user logs in.


ssh-agent needs to be properly setup. In particular the SSH_AUTH_SOCK environment variable needs to be present in the user's session. The specifics on how to do this are outside of the scope of this document.

Not using gpg-agent from GPG2. In the future seahorse-agent may integrate with the gpg-agent, but for now it replaces it.

A build 0.9.9 or later of Seahorse.

Starting seahorse-agent the Sloppy Way

seahorse-agent tries to make it easy for first time users and when started without options does various nasty things to hook into GPG and SSH running in the session. In particular:

  • Edits gpg.conf
  • Moves the socket pointed to by the SSH_AUTH_SOCK environment variable and replaces it with its own.

This is hokey. But it allows the user to run seahorse-agent from the gnome-session-manager, or from within the session.

Starting seahorse-agent Properly

There are two ways to start seahorse-agent properly:

  1. From a script. Call seahorse-agent using the --variables argument to print out environment variables, and then source those into the script.
  2. Using the --execute argument to chain the startup of seahorse-agent into your session.

Using --variables to Print Environment

When called with the --variables option the daemon will print environment variables instead of doing the above nasty file editing. These environment variables should be included in the user's session before other programs start.

This can be done by adding a line like this to .gnomerc or a distro specific session startup script:

eval `seahorse-agent --variables`

Note that because seahorse-agent uses the SSH_AUTH_SOCK info it must be started after ssh-agent. This is tricky.

Using --execute to Chain Startup

ssh-agent and dbus-launch both allow executing another program once the main daemon has started. seahorse-agent allows this too. Your startup session startup command might look like:

ssh-agent dbus-launch --exit-with-session seahorse-agent --execute gnome-session

In turn the above command will:

  1. Start up ssh-agent. Once it has forked it...
  2. Starts up dbus-launch. Once it has started DBUS it...
  3. Executes seahorse-agent. And when it is ready it ...
  4. Runs gnome-session

Each of these commands needs to insert environment variables into the session and pass them on to the next process in that order.

Starting seahorse-agent in Ubuntu

The following is only necessary on Ubuntu 6.06 (Dapper Drake) on Ubuntu 6.10 (Edgy Eft) this is done automatically with the installation.

Write the following text to /etc/X11/Xsession.d/70seahorse-agent

# This file is sourced by Xsession(5), not executed.
STARTUP="/usr/bin/seahorse-agent --execute $STARTUP"

This will chain seahorse-agent properly into the startup.

The SSH agent startup script in that folder needs to have a higher number than the '70' in the file name. (Yes, that seems backwards, but that's how it works.)

Starting seahorse-agent in Slackware

Write the following text to ~/.xsession

ssh-agent dbus-launch --exit-with-session seahorse-agent --execute gnome-session

Starting seahorse-agent in Gentoo

By default, when login in from gdm, X startup scripts will not read .xsession unless you are using a custom session (by selecting custom in gdm, at this point, you can refer to "Using --execute to Chain Startup") so you have to put the following in your .xprofile:

eval `seahorse-agent --variables`

or you can alternatively drop

# launches a seahorse-agent instance 

seahorseagent="`which seahorse-agent 2> /dev/null`"
if [ -n "$seahorseagent" ] && [ -x "$seahorseagent" ] && [ -z "$GPG_AGENT_INFO" ]; then
        #echo "Starting seahorse-agent"
        command="$seahorseagent --execute $command"

into /etc/X11/xinit/xinitrc.d/70-seahorse-agent.

Note: if you are using keychain, you will probably need to unset SSH_AGENT_PID to get keychain to see the ssh-agent launched by gdm and hidden by seahorse. At this time, keychain doesn't see seahorse-agent as a gpg agent because of how it looks at gpg agent pids.

Starting seahorse-agent in ALT Linux

seahorse-agent in ALT Linux systems (stable branches as well as Sisyphus) automatically integrates with ssh-agent (nothing should be done manually), but does little about gpg-agent. Make sure that 'use-agent' in your ~/.gnupg/gpg.conf is commented out (or doesn't exist at all), if you want seahorse-agent to work with your GPG keys.

Other Distros

Please add specifics here...

Apps/Seahorse/SessionIntegration (last edited 2013-11-19 17:27:10 by WilliamJonMcCann)