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 pete@email.com to correct errors or typos.
.TH man 1 "29 April 2015" "1.0" "Pete Man Page"
.SH NAME
pete \- Professional Linux Geek
.SH SYNOPSIS
Pete is a Linux Geek who lives in Pennsylvania USA
.SH DESCRIPTION
.PP
Pete Vargas Mas
.br
RHCE, MCITP, MCSA, MCTS, Linux+, LPIC-2
.br
Professional Linux Geek
.br
Cell Phone:  (+1) 515-555-1212
.br
E-mail: pete@email.com
.PP
.SH OPTIONS
Pete does like Starbucks Venti Skinny Cinnamon Dolce Latte no-whip…hint…
.SH SEE ALSO
Minion(8), Minion(8), Minion(8)
.SH BUGS
No known bugs this week.
.SH AUTHOR
Pete Vargas Mas (pete@email.com)


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
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:


cd ../SOURCES
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

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

%prep
%setup -q

%build

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

%clean
rm -rf $RPM_BUILD_ROOT

%files
%defattr(-,root,root,-)
/usr/share/man/man8/pete.1.gz

%changelog
* 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: pete@email.com
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
/home/pete/.gnupg/pubring.gpg
---------------------------------
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.
rpmbuild/RPMS/noarch/pete-1.0-1.el6.noarch.rpm:
[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: linuxserver.vargasmas.com
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
=====================================================================================================================================
Installing:
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

Installed:
  pete.noarch 0:1.0-1.el6

Complete!
[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.