How to create a custom Linux man page and deploy it as a rpm file

Knowing how to create and deploy your own Linux man pages can make documentation a lot easier to access for your users and co-workers. Here is a process that you can use to make a man page, install it, and even deploy it via a gpg-signed rpm file. In the following examples, I am using a Red Hat Enterprise Linux 6 server, and I am logged in as an unprivileged userid (pete). You can also follow this example on CentOS or Fedora.

Create a man page

Using your favorite text editor, create your man page text file. See  man 7 mdoc for 
information on how the markup language shown in the following example works:

.\" Manpage for Pete.
.\" Contact to correct errors or typos.
.TH man 1 "29 April 2015" "1.0" "Pete Man Page"
pete \- Professional Linux Geek
Pete is a Linux Geek who lives in Pennsylvania USA
Pete Vargas Mas
Professional Linux Geek
Cell Phone:  (+1) 515-555-1212
Pete does like Starbucks Venti Skinny Cinnamon Dolce Latte no-whip…hint…
Minion(8), Minion(8), Minion(8)
No known bugs this week.
Pete Vargas Mas (

I created the above file in my home directory (/home/pete), and named the file  pete.1 .

At this point, you can view the formatted man page using the command:    man ./pete.1
Remember, the    man 7 mdoc  command will display a page that describes all the macros
you can use when creating a man page.

Install the MAN Page

From the command line:

install –g 0 –o 0 –m 0644 pete.1 /usr/local/man/man8/
gzip /usr/local/man/man8/pete.1

Now you should be able to view your manpage using:    man pete

How to prepare the custom man page for installation via RPM

If you don’t have an environment for building custom RPM files, then do this in your home directory:

sudo yum install rpm-build rpm-devel rpmdevtools rpmdev-setuptree
echo “%_sourcedir %{_topdir}/SOURCES/%{name}-%{version}” >> ~/.rpmmacros

Now you can create a skeleton spec file:

cd ~/rpmbuild/SPECS
rpmdev-newspec pete.spec

Create the source tar ball in the SOURCES/ directory, using the previously created pete.1.gz file:

mkdir –p pete-1.0/
cp /usr/local/man/man8/pete.1.gz pete-1.0/
tar cvzf pete-1.0.tar.gz ./pete-1.0/
mv pete-1.0.tar.gz ./pete-1.0/
cd ../SPECS

Edit the spec file:

Use your favorite text editor to edit the spec file shell created earlier:

vi pete.spec

Here’s an example of what my spec file looks like:

Name:           pete
Version:        1.0
Release:        1%{?dist}
Summary:        Pete Documentation
Group:          Testing
License:        GPL
Source0:        %{name}-%{version}.tar.gz
BuildArch:      noarch
Vendor:         VargasMas Consulting
Packager:       Pete Vargas Mas

This is a test. We are trying to install a
sysadmin generated man page from a rpm file.
Just to prove we can.

%setup -q


mkdir -p $RPM_BUILD_ROOT/usr/share/man/man8
install pete.1.gz $RPM_BUILD_ROOT/usr/share/man/man8



* Wed Apr 29 2015  -
- Initial build.

Now save your spec file and create the rpm file:

rpmbuild –ba pete.spec

Look in the ../RPMS/noarch/ directory for your newly created rpm file!

Can we sign our RPM with a GPG Key?

Yes we can! You can use an existing gpg key pair to sign your rpm file.
If you don’t already have a gpg key pair, we can create one as shown in the following example:

[pete@linuxserver ~]$ mkdir ~/.gnupg

[pete@linuxserver ~]$ gpg --gen-key
gpg (GnuPG) 2.0.14; Copyright (C) 2009 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
   (1) RSA and RSA (default)
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
Your selection? 1
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048)
Requested keysize is 2048 bits
Please specify how long the key should be valid.
         0 = key does not expire
        = key expires in n days
      w = key expires in n weeks
      m = key expires in n months
      y = key expires in n years
Key is valid for? (0) 1y
Key expires at Thu 28 Apr 2016 11:24:48 AM EDT
Is this correct? (y/N) y

GnuPG needs to construct a user ID to identify your key.

Real name: Pete Vargas Mas
Email address:
Comment: Pete's RPM Signing Key
You selected this USER-ID:
    "Pete Vargas Mas (Pete's RPM Signing Key) "

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
You need a Passphrase to protect your secret key.
(At this point, you will enter a passphrase...)

can't connect to `/home/pete/.gnupg/S.gpg-agent': No such file or directory
gpg-agent[30638]: directory `/home/pete/.gnupg/private-keys-v1.d' created
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.

gpg: /home/pete/.gnupg/trustdb.gpg: trustdb created
gpg: key 13B81880 marked as ultimately trusted
public and secret key created and signed.

gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
gpg: next trustdb check due at 2016-04-28
pub   2048R/13B81880 2015-04-29 [expires: 2016-04-28]
      Key fingerprint = 0BE5 04F4 86EA 43A3 740B  24CC 88D7 94E0 13B8 1880
uid                  Pete Vargas Mas (Pete's RPM Signing Key)
sub   2048R/48AE8EB3 2015-04-29 [expires: 2016-04-28]

[pete@linuxserver ~]$

You can list all your gpg keys and see the new key:

[pete@linuxserver ~]$ gpg --list-keys
pub   2048R/13B81880 2015-04-29 [expires: 2016-04-28]
uid                  Pete Vargas Mas (Pete's RPM Signing Key)
sub   2048R/48AE8EB3 2015-04-29 [expires: 2016-04-28]

[pete@linuxserver ~]$

Now export the GPG key to a file, by specifying the uid of the key to export:

[pete@linuxserver ~]$ gpg --export -a 'Pete Vargas Mas' > RPM-GPG-KEY-PeteVargasMas

Import the GPG key into the rpm keyring:

[pete@linuxserver ~]$ sudo rpm --import RPM-GPG-KEY-PeteVargasMas

Check that rpm is aware of your gpg key:

[pete@linuxserver ~]$ rpm -q gpg-pubkey --qf '%{name}-%{version}-%{release} --> %{summary}\n'

gpg-pubkey-0608b895-4bd22942 --> gpg(EPEL (6) )
gpg-pubkey-13b81880-5880f80a --> gpg(Pete Vargas Mas (Pete's  RPM Signing Key) )

Add the following two lines to the bottom of your ~/.rpmmacros file:

%_signature gpg
%_gpg_name  Pete Vargas Mas

This will tell the rpmbuild command (that we’ll be using later) which users gpg key to use for signing.

Now we can use the RPM command to sign our rpm file with the GPG Key:

[pete@linuxserver ~]$ rpm --addsign rpmbuild/RPMS/noarch/pete-1.0-1.el6.noarch.rpm
Enter pass phrase:
Pass phrase is good.
[pete@linuxserver ~]$

To verify that we have a signed rpm file, use the “rpm –qpi” command as in the following example:

[pete@linuxserver ~]$ rpm -qpi rpmbuild/RPMS/noarch/pete-1.0-1.el6.noarch.rpm
Name        : pete                         Relocations: (not relocatable)
Version     : 1.0                               Vendor:
Release     : 1.el6                         Build Date: Wed 29 Apr 2015 10:40:48 AM EDT
Install Date: (not installed)               Build Host:
Group       : Testing                       Source RPM: pete-1.0-1.el6.src.rpm
Size        : 494                              License: GPL
Signature   : RSA/SHA1, Wed 29 Apr 2015 11:37:27 AM EDT, Key ID 88d784e013b81880
Packager    : Pete Vargas Mas
Summary     : Pete Documentation
Description :
This is a test. We are trying to install a
sysadmin generated man page from a rpm file.
Just to prove we can.
[pete@linuxserver ~]$

Now you can install your custom RPM file using yum:

[pete@linuxserver ~]$ sudo yum localinstall /home/pete/rpmbuild/RPMS/noarch/pete-1.0-1.el6.noarch.rpm
Loaded plugins: downloadonly, rhnplugin, security
Setting up Local Package Process
Examining /home/pete/rpmbuild/RPMS/noarch/pete-1.0-1.el6.noarch.rpm: pete-1.0-1.el6.noarch
Marking /home/pete/rpmbuild/RPMS/noarch/pete-1.0-1.el6.noarch.rpm to be installed
rhel-x86_64-server-6                                                                        | 1.5 kB     00:00
rhel-x86_64-server-optional-6                                                               | 1.5 kB     00:00
Resolving Dependencies
--> Running transaction check
---> Package pete.noarch 0:1.0-1.el6 will be installed
--> Finished Dependency Resolution

Dependencies Resolved

Package                  Arch                       Version                        Repository                                  Size
pete                     noarch                     1.0-1.el6                      /pete-1.0-1.el6.noarch                     494

Transaction Summary
Install       1 Package(s)

Total size: 494
Installed size: 494
Is this ok [y/N]: y
Downloading Packages:
Running rpm_check_debug
Running Transaction Test
Transaction Test Succeeded
Running Transaction
  Installing : pete-1.0-1.el6.noarch                                                                                             1/1
  Verifying  : pete-1.0-1.el6.noarch                                                                                             1/1

  pete.noarch 0:1.0-1.el6

[pete@linuxserver ~]$

If you want to distribute your rpm file to the public, you will need to sign your rpm with a gpg key that has been uploaded to a public keyserver (that’s a separate article!), or give the recipient a copy of your PUBLIC gpg key (the RPM-GPG-KEY-PeteVargasMas I created earlier) so they can verify the rpm file on their own.

No comments: