diff options
Diffstat (limited to 'slackupgrade.8')
-rw-r--r-- | slackupgrade.8 | 262 |
1 files changed, 262 insertions, 0 deletions
diff --git a/slackupgrade.8 b/slackupgrade.8 new file mode 100644 index 0000000..b962db5 --- /dev/null +++ b/slackupgrade.8 @@ -0,0 +1,262 @@ +.\" This file is part of slackupgrade +.\" Copyright (C) 2019 Sergey Poznyakoff. +.\" +.\" Slackware-upgrade-system is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as published +.\" by the Free Software Foundation; either version 3, or (at your option) +.\" any later version. +.\" +.\" Slackware-upgrade-system is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with slackupgrade. If not, see +.\" <http://www.gnu.org/licenses/>. +.TH SLACKUPGRADE 8 "September 23, 2019" "SLACKUPGRADE" "System Manager's Manual" +.SH NAME +slackwupgrade \- do a full upgrade of a Slackware installation +.SH SYNOPSIS +.nh +.na +\fBslackupgrade\fR\ + [\fB\-anqvy\fR]\ + [\fB\-k \fIFILE\fR]\ + [\fB\-p \fIPACKAGE\fR\]\ + [\fB\-s \fISERIES\fR]\ + [\fIURL\fR] +.ad +.hy +.SH DESCRIPTION +Upgrades the Slackware installation to a new release. The \fIURL\fR +argument supplies the URL of the Slackware distribution or the +directory on the local filesystem where it can be found. If not +given, the program will use the nearest next version distribution +from +.nh +.BR https://mirrors.slackware.com . +.hy +.PP +When started, the program first verifies that it runs with root +privileges on a Slackware installation and determines the current +release version number. Then it verifies the distribution \fIURL\fR: +it must contain the files \fBCHECKSUMS.md5\fR, +\fBANNOUNCE.\fIVERSION\fR and the Slackware package series +directories. +.PP +The file \fBCHECKSUMS.md5\fR and its GPG signature are downloaded +first. Then, the program verifies that the signature is correct. +For this to succeed, you must have the Slackware Linux Project +public key in your keyring. If you don't, run +.PP +.EX +curl -o - https://www.slackware.com/gpg-key | gpg --import +.EE +.PP +When this initial check is passed, the program constructs two lists +of packages: a list of currently installed packages and a list of +packages available in the distribution. When constructing the list of +available packages, known differences between Slackware releases are +taken into account. For example, consider upgrade from version 14.1 to +14.2. It is known that the \fIportmap\fR package from 14.1 is +replaced with the \fIrpcbind\fR in version 14.2. Consequently, if the +program sees that \fIportmap\fR is installed on the system, it will +include \fIrpcbind\fR to the list of installation candidates. +Information about package differences in various versions is kept in +\fIreplacement map files\fR. See the section \fBREPLACEMENT MAP\fR, +for a discussion of these files. +.PP +The difference between these two lists, is the set of installed +packages that have no equivalent in the available package list. Those +are \fIorphaned packages\fR, which were either removed from the Slackware +distribution, or were installed from third-party sources. It is +unpredictable whether or not these will work on the newly upgraded +system, therefore they will be removed after a successful upgrade. +Before proceeding, the program will display this list on the screen +and save it in file +.nh +\fB/var/log/slackupgrade-\fIOLD\fR-\fINEW\fB.removed\fR +.hy +for your consideration (here, \fIOLD\fR and \fINEW\fR stand for the +current and new Slackware version numbers, correspondingly). After +the upgrade, you can re-install them, if necessary. +.PP +After this step, the program will print the current Slackware version +and the version you are going to upgrade to, and will ask you to +confirm that you really want to upgrade. This is the right moment to +quit if you decide to modify program invocation in order to handle +orphaned packages. +.PP +If you do, type \fBno\fR. You have two options. First, if there are +any orphaned packages that you want to keep in place, create a +\fIkeep-list\fR file. This file should contain names of those +packages, each name on a separate line. When you restart the program +use the \fB\-k \fIFILE\fR\fR option to instruct it to use this file. +.PP +Secondly, if you are upgrading to the version for which there is no +replacement map, there can be replacement packages for some of the +orphaned ones. You can create a replacement map and save it to +the \fB/etc/slackupgrade\fR directory (see the section +\fBREPLACEMENT MAP\fR for details). If you do, please drop me a note +so that your changes become available for other users (see the +\fBBUGS\fR section, for contact information). You can also use the +\fB\-p\fR command line option to provide the names of replacement +packages from the command line. +.PP +By default, the program will upgrade only the packages actually +installed on your system. You can request to install additional +series from the distribution with the \fB\-s\fR option. E.g., it is +often a good idea to install all packages from series \fBl\fR, like that: +.PP +.EX +slackupgrade \-s l +.EE +.PP +Otherwise, you can request to install all missing packages from all +series, excepting \fBkde*\fR, by running the command with the +\fB\-a\fR option. +.PP +At the end of the run, the program prints additional instructions and +leaves the detailed log in file +.nh +\fB/var/log/slackupgrade-\fIOLD\fB\-\fINEW\fB.log\fR. +.hy +.sp +Here, \fIOLD\fR and \fINEW\fR stand for the old and new Slackware +release versions, correspondingly. +.PP +If any configuration files were created during the upgrade that +conflict with the existing files, they will be stored alongside the +original files, with the \fB.new\fR extension. The list of these +files will be stored in file +\fB/var/log/slackupgrade\-\fIOLD\fB\-\fINEW\fB.conffiles\fR. +.SH OPTIONS +.TP +.B \-a +Install all series except \fBkde*\fR. +.TP +.B \-h +Display a short help summary and exit. +.TP +\fB\-k \fIFILE\fR +After successful upgrade, \fBslackupgrade\fR will remove +previously installed packages that are not available in the new +distribution. This option allows you to supply a list of packages +that should not be removed. Each line in \fIFILE\fR should list +exactly one package name, without version and architecture +information. Empty lines and comments (\fB#\fR) are ignored. +.sp +To obtain initial list of packages that will be removed, run the +program with the \fB\-n\fR option. At the end of the run, the list +will be stored in file +.nh +\fB/var/log/slackupgrade-\fIOLD\fR-\fINEW\fB.removed\fR. +.hy +At a pinch (not really recommended), you can move it elsewhere and use +as argument to that option. This way all packages will be preserved. +.TP +.B \-n +Dry-run mode: do nothing, print what would have been done. In spite +of the name, the list of packages for removal will still be created. +.TP +\fB\-p \fIPACKAGE\fR +Install additional package. +.TP +.B \-q +Quiet mode: suppress all messages, except error diagnostics. +.TP +\fB\-s \fISERIES\fR +Additionally install all packages from \fISERIES\fR. +.sp +You can use this option together with \fB\-a\fR to install entire +Slackware system, like that: +.sp +.nh +.na +slackupgrade -a -s kde -s kdei +.ad +.hy +.TP +.B \-v +Verbosely list each package being upgraded or removed. +.TP +.B \-y +Assume "yes" to all queries. +.SH REPLACEMENT MAP +Replacement map files contain names of packages that have been +replaced with another packages in the new release. They are stored in +the \fB/etc/slackupgrade\fR directory. Each replacement +map is named \fIOLD\fB\-\fINEW\fB.repl\fR, where \fIOLD\fR and +\fINEW\fR are two subsequent versions of Slackware. For example, the +file \fB/etc/slackupgrade/14.1\-14.2.repl\fR contains +changes in package names between versions 14.1 and 14.2. +.PP +This version of \fBslackupgrade\fR is shipped with two +replacement maps, for upgrades between 14.0 and 14.1, and between 14.1 +and 14.2. +.PP +A replacement map is a plaintext file with each package being described +on a separate line. Lines consist of two or more columns separated +with any amount of whitespace. Column one contains the name of the +package in the version \fIOLD\fR of Slackware. Column two contains +the name of the corresponding package in Slackware version \fINEW\fR. +If the package was spli into several packages, additional packages can +be listed on the same line. +.PP +Excessively long lines can be +split over several physical lines by using the traditional UNIX +approach: prefix and each line that must be joined with the next one +with a backslash immediately followed by a newline character. +.PP +Comments are introduced with the hash sign (\fB#\fR) and extend to the +nearest newline character. Empty lines and comments are ignored. +.SH FILES +.TP +\fB/etc/slackupgrade/\fIOLD\fB\-\fINEW\fB.repl\fR +Replacement map for upgrades from version \fIOLD\fR to \fINEW\fR. +.TP +\fB/var/log/slackupgrade\-\fIOLD\fB\-\fINEW\fB.log\fR +Detailed log of operations performed during the upgrade from version +\fIOLD\fR to \fINEW\fR. +.TP +\fB/var/log/slackupgrade\-\fIOLD\fB\-\fINEW\fB.conffiles\fR +List of the new incoming config files on your system with the +\fB.new\fR extension. You may need to merge them with your actual +files, or move them over, or simply remove them. In any case, it is +good idea to carefully consider each of them. +.TP +\fB/var/log/slackupgrade-\fIOLD\fR-\fINEW\fB.removed\fR +The list of packages that were removed from the system. Examine it. +You may need to re-install some or all of them from third-party +servers or from slackbuilds. +.SH "SEE ALSO" +The \fBUPGRADE.TXT\fR document, outlining the procedure as a whole: +.nh +<\fBhttps://mirrors.nix.org.ua/linux/slackware/slackware\-14.1/UPGRADE.TXT\fR>. +.hy +.PP +.BR upgradepkg (8). +.SH BUGS +Only main Slackware packages are considered. The \fBpatches\fR +subdirectory is not used. +.PP +Report bugs to <gray@gnu.org>. +.SH COPYRIGHT +Copyright \(co 2019 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later +<http://gnu.org/licenses/gpl.html> +.br +.ad +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.\" Local variables: +.\" eval: (add-hook 'write-file-hooks 'time-stamp) +.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \"" +.\" time-stamp-format: "%:B %:d, %:y" +.\" time-stamp-end: "\"" +.\" time-stamp-line-limit: 20 +.\" end: + |