This is Gentoo's testing wiki. It is a non-operational environment and its textual content is outdated.

Please visit our production wiki at https://wiki.gentoo.org

User:Maffblaster/Drafts/Gentoo Primers/The Gentoo Developer Primer

From Gentoo Wiki (test)
Jump to:navigation Jump to:search

This document should not be considered a replacement for the old Developer Handbook. Eventually this article may get merged into the Developer Handbook. Right now it is simply to be used as a draft space of steps necessary for developers to become connected and productive in the Gentoo sphere. New developers should travel down through the list.

Developer init

New developers have quite a few things to setup before they're 'fully integrated' into the Gentoo ecosystem. For developers that are unfamiliar with processes and job duties of system administration (perhaps more code-savvy and less infrastructure oriented developers), configuring these things can be a confusing and difficult. Because of the sheer amount of tasks, it's also easy to

Keys

SSH

SSH keys will need to be generated so that woodpecker, and potentially Gentoo development machine, can be accessed. The recruiter(s) will assist in this process, but essentially generate a 4096-bit RSA key pair:

user $ssh-keygen -t rsa -b 4096

Be sure to enter a strong passphrase. Do not leave the passphase blank!

After generation, the keys will be located in ~/.ssh/ directory. The public key (typically found at ~/.ssh/id_rsa.pub) will be added to Woodpecker for you by your recruiter. The private key (found at ~/.ssh/id_rsa) should never leave the machine and should only be readable by your user:

user $ls -lha ~/.ssh/
-rw------- 1 larry users 1.7K Jun 15 09:56 id_rsa
-rw-r--r-- 1 larry users  396 Jun 15 09:56 id_rsa.pub

See the SSH article for more information.

Configuration file

Those working with multiple SSH keys can setup an SSH configuration file in order to conveniently associate SSH keys with remote hosts. For example, if a developer suppose Larry, our favorite cow, has three separate SSH keys: one for personal use, one for work, and one for Gentoo work. He can make SSH aware of such a setup by creating a config file in ~/.ssh/ directory:

FILE ~/.ssh/configConfiguring multiple SSH keys
# Work key
Host work-server
    HostName work-server
    IdentityFile ~/.ssh/id_rsa_work
    User larry

# Personal key
Host personal-server
    HostName personal-server
    IdentityFile ~/.ssh/id_rsa_personal
    User larry

# Gentoo key
Host woodpecker
    HostName woodpecker
    IdentityFile ~/.ssh/id_rsa_gentoo
    User larry

Many more configuration options are possible. Investigate in man 5 ssh_config.

GPG

Create a backup

Those without existing GPG keys should skip this section. Creating a backup is best practice for those who have existing GPG keys from other projects:

user $umask 077
user $tar -cf ~/gnupg-backup.tar -C ~/.gnupg

If anything in the following steps goes foul the backup is now located at ~/gnupg-backup.tar.

Master keys

It is best practice for developers to generate a master key pair, then generate subkeys from the master key pair for signing. Generated keys are to follow the specifications outlined in GLEP 63. In short, Gentoo developers are to use a master key type of RSA at 4096 bits (RSAv4 or later). Developers who have already generated a master key that does not meet this minimum standard will need to generate a new set of keys (sorry!).

After emerging app-crypt/gnupg, issue the following commands:

user $mkdir --parents ~/.gnupg/
user $touch ~/.gnupg/gpg.conf

Copy and paste the following GLEP 63 approved configuration template into gpg.conf:

FILE ~/.gnupg/gpg.confCopy/paste GLEP 63 template
# Sets the default signing key (uncomment and fill out after generating 
# a signing subkey):
# default-key 7256DA2CCC1ED5F7

keyserver pool.sks-keyservers.net

emit-version

default-recipient-self

# The sections below are adapted from the RiseUp.net OpenPGP best practices;
# many of them are also in the Debian GPG documentation.

# When outputting certificates, view user IDs distinctly from keys:
fixed-list-mode

# long keyids are more collision-resistant than short keyids (it is trivial
# to make a key with any desired short keyid)
# NOTE: this breaks kmail GnuPG support!
keyid-format 0xlong

# When multiple digests are supported by all recipients, choose the strongest one
# in descending order. GLEP 63 recommends SHA256; SHA512 is better:
personal-digest-preferences SHA512 SHA384 SHA256 SHA224

# Preferences chosen for new keys should prioritize stronger algorithms: 
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 BZIP2 ZLIB ZIP Uncompressed

# All developers should be using an agent for password entry
# (similar arguments as https://www.debian-administration.org/users/dkg/weblog/64):
use-agent

# This makes it possible to know at a glance which user IDs GPG thinks are legitimately 
# bound to the keys in the keyring:
verify-options show-uid-validity
list-options show-uid-validity

# Include an unambiguous indicator of which key made a signature:
# (see http://thread.gmane.org/gmane.mail.notmuch.general/3721/focus=7234)
# (and http://www.ietf.org/mail-archive/web/openpgp/current/msg00405.html)
sig-notation issuer-fpr@notations.openpgp.fifthhorseman.net=%g

# When making an OpenPGP certification, use a stronger digest than SHA1.
# GLEP 63 outlines at least SHA256; SHA512 is better:
cert-digest-algo SHA512

Generate the master key pair by running the following command, then entering the values found in the numbered section below:

user $gpg --full-generate-key

At the dialog:

  1. Choose the "RSA and RSA" option (should be the default).
  2. For key length, be sure to enter 4096.
  3. Enter the GLEP 63 recommended value of 3y for the key expiration.
  4. Enter a name, the email address, and a comment (if desired) to be associated with this key. The comment is simply for your reference. Those with multiple master keys may enter a descriptor describing the purpose of this key in this field.
  5. Visually inspect the data is correct, then confirm the entries by pressing the O key (O as in Oscar) and Enter.
  6. Enter a strong passphrase (be sure include at least one integer number in the passphrase or GPG will provide a warning).

GPG should now be generating a master key pair! This will take some time and will benefit from system resource usage. Updating some software, playing a game, or reviewing bugs is a nice way to pass the time. When finished, the keys will be present in the ~/.gnupg/ directory!

Subkeys

According to GLEP 63 signing subkeys are optional. If the developer would like to use subkeys instead of the master key pair for signing, this section will provide instructions on how to do so. GLEP 63 recommends a 1 year maximum expiration on subkeys with a renewal every 6 months.

Get the master key's ID:

user $gpg --list-public-keys --keyid-format 0xlong larry@gentoo.org
pub   rsa4096/0x7256DA2CCC1ED5F7 2015-03-06 [SC] [expires: 2019-07-01]
      B9CA1534FACDBEB2FC8C14BA2636DA8BCB1ED4A1
uid                   [ultimate] Larry the Cow (larry) <larry@gentoo.org>

In this example 0x7256DA2CCC1ED5F7 is master key's ID; this is what is needed in the next command:

user $gpg --edit-key 0x7256DA2CCC1ED5F7

This will make gpg enter into an interactive mode:

gpg>addkey
Please select what kind of key you want:
   (3) DSA (sign only)
   (4) RSA (sign only)
   (5) Elgamal (encrypt only)
   (6) RSA (encrypt only)
  1. Select "RSA (sign only)" (typically 4).
  2. On the next prompt be sure to enter a value of 4096 for the bit size.
  3. Set the expiration to a value of 1y and confirm.
  4. Enter the passphrase of the master key.

After some time the signing subkey will be generated.

In order to set this subkey to be the default for signing the gpg configuration file will need to be adjusted. Use the --list-public-keys option again to determine the newly generated subkey's ID:

user $gpg --list-public-keys --keyid-format 0xlong larry@gentoo.org
pub   rsa4096/0x7256DA2CCC1ED5F7 2015-03-06 [SC] [expires: 2019-07-01]
      B9CA1534FACDBEB2FC8C14BA2636DA8BCB1ED4A1
uid                   [ultimate] Larry the Cow (larry) <larry@gentoo.org>
sub   rsa4096/0x0267E2D1C318315B 2017-01-20 [S] [expires: 2018-06-23]

The subkey should be displayed at the bottom of the list. The subkey ID in this example is 0x0267E2D1C318315B.

Open the file and uncomment the line referencing default-key:

FILE ~/.gnupg/gpg.confAdd default signing subkey
# Sets the default signing key (uncomment and fill out after generating 
# a signing subkey):
default-key 0x0267E2D1C318315B # Replace with correct subkey ID.

Remember, this subkey will be expired in one year from the generation date. When it is expired a generate a new subkey by following the steps above.

Sending keys

Once all keys have been created, it is necessary to send them to keyserver pools:

user $gpg --keyserver keys.gnupg.net --send-keys <key>
Revocation certificate
Pinentry

pinentry should be configured based on developer preference. There are a few visual interfaces to pinentry: Qt, GTK, and ncurses. Adjust the USE flags for the program as necessary. If the KDE or GNOME desktop environments are being used, it is likely either the qt5 (or perhaps qt4) or the gtk USE flags have respectively been set.

After adjusting USE flags and recompiling as necessary, be sure to use eselect to select the appropriate user interface. In the example below the Qt 5 interface has been selected:

root #eselect pinentry list
Available pinentry binary implementations:
  [1]   pinentry-gnome3
  [2]   pinentry-qt *
  [3]   pinentry-gtk-2
  [4]   pinentry-qt4
  [5]   pinentry-curses
  [6]   pinentry-tty

Next configure the developers ~/.gnupg/gpg-agent.conf file to prompt for a password via pinentry:

FILE ~/.gnupg/gpg-agent.conf
pinentry-program /usr/bin/pinentry
no-grab
default-cache-ttl 1800

Sites

Woodpecker

Woodpecker is primary used to setup a developer's LDAP information and add developer mail addresses to email alaises. These changes are actioned using the perl_ldap script.

Each change will require you to enter a password.

LDAP

Lightweight directory access protocol is used by Gentoo's infrastructure team in order to maintain an internal database of information about Gentoo developers. This rehashes the basics of setting developer information in LDAP. See Infrastructure's LDAP Guide for the latest updates.


If Larry were to add himself to some roles for Gentoo, he would execute the following command:

user $perl_ldap -b $(whoami) -M gentooRoles "Eat grass, Roll in the mud, Look nice, Moo" $(whoami)

Although you can name them whatever you'd like, your roles should match your project affiliations defined on by your actual project involvement. Ideally your involvement will line up with your Developer infobox here on the wiki.

Set longitude and latitude information (find it on a per-city basis here):

user $perl_ldap -b $(whoami) -M lat "47.6588889" $(whoami)
user $perl_ldap -b $(whoami) -M lon "-117.425" $(whoami)

Setting longitude and latitude in LDAP will enable your location marker to show up on the developer map.

Email
GPG key

perl_ldap expects the GPG signing key to be passed in fingerprint format. The following command will show the fingerprint format for subkeys (and no, the double --with-fingerprint is not a typo):

user $gpg --with-fingerprint --with-fingerprint --list-keys larry@gentoo.org
pub   rsa4096 2015-03-06 [SC] [expires: 2018-04-24]
      B3BC 1524 FCBD BEG2 AD2C  39CE 2606 GA1F CB2E D3F1
uid           [ultimate] Larry the Cow (larry) <larry@gentoo.org>
sub   rsa4096 2015-03-06 [E]
      GB3E ABFG CD4E C349 CE15  519A F2FA 0143 4A03 GAG2
sub   rsa4096 2017-01-20 [S] [expires: 2018-04-15]
      8712 75C0 FCG2 C8A9 32C4  D149 0100 DAF1 C355 812C

In the above example 8712 75C0 FCG2 C8A9 32C4 D149 0100 DAF1 C355 812C is the signing key in the fingerprint format.

Bugzilla

Wiki

Visit the Developer Central page and click the "Getting started" link in order to connect your LDAP information to the wiki.

GitHub

Until a better, self-hosted system can be implemented, Gentoo is using GitHub to accept community contributions. Gentoo developers should create a GitHub account and add the following:

  • Add your public GPG key to your GitHub profile.
  • Add your public SSH key to your GitHub profile.
    • Developer can alternatively use SSH forwarding instead of adding their public key to GitHub's server (requires more time/effort).
  • Two-factor authentication (optional, but recommended for developers with a phone).
    • Personal access tokens (if two-factor authentication is enabled). Enable the following scopes for Gentoo related access tokens:
      • repo
      • admin:org
      • read:public_key
      • admin:repo_hook
      • gist
      • read:user
      • user:email
      • delete_repo
      • read:gpg_key
      • Add the Gentoo development token to the ~/.gitconfig file.
    • Use SSH URLs (alternative to access tokens).

Collaboration and community

Git

make.conf

All Gentoo developers should have GPG (PGP) and SSH keys (generated in the Keys section above). Git needs to interface with both keys. This is done in order to verify and validate identity.

user $gpg --list-public-keys --keyid-format 0xlong larry@gentoo.org
pub   rsa4096/0x7256DA2CCC1ED5F7 2015-03-06 [SC] [expires: 2019-07-01]
      B9CA1534FACDBEB2FC8C14BA2636DA8BCB1ED4A1
uid                   [ultimate] Larry the Cow (larry) <larry@gentoo.org>
sub   rsa4096/0x0267E2D1C318315B 2017-01-20 [S] [expires: 2018-06-23]

In this example 0x0267E2D1C318315B is the part that would be added a value to the PORTAGE_GPG_KEY variable inside make.conf:

Configuration file

The options can be added via git config by running the following commands:

user $git config --global user.email "Larry the cow"
user $git config --global user.email "larry@gentoo.org"
user $git config --global user.signingKey 0x0137D2F1C328917A
user $git config --global commit.gpgsign true
user $git config --global format.signOff true
user $git config --global push.gpgSign True
user $git config --global gpg.program gpg

When the above commands have been entered, the developer's git configuration file should look something like the following:

FILE ~/.gitconfig
[user]
        name = Larry the cow
        email = larry@gentoo.org
        signingkey = 0x0137D2F1C328917A
[credential]
        helper = cache --timeout=3600
[push]
        default = simple
        gpgSign = True
[format]
        signOff = true
[commit]
        gpgsign = true
[gpg]
        program = gpg

IRC

Most developers stay connected 24/7 to IRC in order to catch any mentions of their nickname. There are various strategies of staying connected. Some developers leave their main workstation connected to the internet, others might pay for an IRC cloud service.

For those wishing to host IRC themselves, the IRC guide is a great place to start.

Tip
Upon passing the quiz and getting a @ next to the IRC handle in the #gentoo-dev channel, it is tradition for fellow developers kick newcomers from the channel. This is done as an initiation ceremony for new developers. For this reason is wise to setup auto-rejoin on the #gentoo-dev channel in the IRC client before getting promoted to developer status. Occasionally the recruiters will warn about this tradition.

Forums

Blog

Many Gentoo developers have blogs. This section will present a few options for Gentoo developers.

The first option is creating a Developer website on Woodpecker, which can be used to host any kind of file. Simply make it a website by adding an index.html file.

The second option for Gentoo developer is to use the Wordpress site, via https://blogs.gentoo.org.

If none of these options work, you can always host the blog somewhere else. As long as it has an tag-generated RSS feed, the Gentoo Planet blog aggregation site can pull in the Gentoo related postings.

Ebuild development

Portage configuration

Package maintainers will need to provide Portage with their GPG signing (denoted by the [S]) key information in 0xlong format. This is a different format than perl_ldap expects on Woodpecker. Use the following command to display keys in the proper format:

user $gpg --list-public-keys --keyid-format 0xlong larry@gentoo.org
pub   rsa4096/0x7256DA2CCC1ED5F7 2015-03-06 [SC] [expires: 2019-07-01]
      B9CA1534FACDBEB2FC8C14BA2636DA8BCB1ED4A1
uid                   [ultimate] Larry the Cow (larry) <larry@gentoo.org>
sub   rsa4096/0x0267E2D1C318315B 2017-01-20 [S] [expires: 2018-06-23]

In this example 0x0267E2D1C318315B is the part that would be added a value to the PORTAGE_GPG_KEY variable inside make.conf:

FILE /etc/portage/make.conf
PORTAGE_GPG_KEY="0x0267E2D1C318315B"


By default Portage does one thing at a time. Adding the following values to Portage's feature will speed up the development process:

FILE /etc/portage 2 EMERGE_DEFAULT_OPTS="--quiet-build=y --keep-going=y --usepkg"/make.conf
# parallel-fetch - speed up Portage's source package downloads by downloading additional package source files while compiling.
# parallel-install - install more than one package at a time (when --jobs is used).
# buildpkg - build binary packages from sources and place them in /usr/portage/packages (by default).
# userfetch - fetches packages with "portage:portage" permissions (hardens Portage's fetch).
# userpriv - compiles code with "portage:portage" permissions (drops root to harden Portage more). if this option is enabled without usersandbox below, then the sandbox is not used.
# usersandbox - runs code in the sandbox with "portage:portage" permissions. necessary to pair this option with userpriv above in order to use the sandbox in usermode.
# sign - needed for Portage development
FEATURES="parallel-fetch parallel-install buildpkg sign userfetch userpriv usersandbox"
FILE /etc/portage/make.conf
EMERGE_DEFAULT_OPTS="--quiet-build=y --keep-going=y --usepkg"

User configuration

Be sure to add the account(s) used for developerment to the Portage group:

root #gpasswd -a <username> portage

This will let the developer modify files owned by Portage (/usr/portage}}.

Tooling

When attempting to preform fine work, having sharp, precise tools is a must. This section of the developer primer will hopefully provide aid in helping developers streamline their workflow. The goal is an increase in productivity.

Shell configuration

bash

dash

fish

zsh

Email clients

Depending on the selected email client, getting setting configured properly to filter incoming messages into nicely organized directories and remove nasty spam can take some time and effort. It is important that every developer take the time to properly configure the email client of choice for developer related duties for a few reasons. A well thought out configuration at the beginning will:

Save time.
For most every developer, checking mail is only one of the streams of communication that will need checked on a regular basis. The less time spent checking mail the more time can be invested into checking other communication streams such as IRC, comments on GitHub, or other Gentoo project sites. Ideally Gentoo developers will be spending the majority of their time on coding, ebuild maintenance, hacking on infrastructure, or other Developer/SysOp duties.
Gain efficiency.
An efficient person is a productive person. Having the mail client sort and prioritize messages offloads cycles to a CPU rather than a human brain, which allows the human brain to concentrate on what is important.

Thunderbird

Useful link for spam filtering:

Remember that Mozilla's spam filter needs training, so it may take some time (a week or two) for it to learn what is spam what is not. Be sure to check whatever folder is dedicated to Junk every once in a while to be sure important messages are not being marked as Junk!

mutt and neomutt

Both {{c|mutt]] and neomutt are available in Gentoo.

Retrieved from "https://wikitest.gentoo.org/index.php?title=User:Maffblaster/Drafts/Gentoo_Primers/The_Gentoo_Developer_Primer&oldid=732562"