man/dpkg-fsys-usrunmess.pod

   1 # dpkg manual page - dpkg-fsys-usrunmess(8)
   2 #
   3 # Copyright © 2020-2021 Guillem Jover <guillem@debian.org>
   4 #
   5 # This is free software; you can redistribute it and/or modify
   6 # it under the terms of the GNU General Public License as published by
   7 # the Free Software Foundation; either version 2 of the License, or
   8 # (at your option) any later version.
   9 #
  10 # This is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 # GNU General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License
  16 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  17
  18 =encoding utf8
  19
  20 =head1 NAME
  21
  22 dpkg-fsys-usrunmess - undoes the merged-/usr-via-aliased-dirs mess
  23
  24 =head1 SYNOPSIS
  25
  26 B<dpkg-fsys-usrunmess> [B<option>...]
  27
  28 =head1 DESCRIPTION
  29
  30 B<dpkg-fsys-usrunmess> is a tool to fix up filesystems that have been
  31 installed anew with recent installers with unfortunate defaults or
  32 migrated to the broken merged /usr via aliased directories layout,
  33 which is B<not> supported by dpkg. See the dpkg FAQ.
  34
  35 B<Note>: In Debian its tech-ctte has decreed that on the release after
  36 bookworm the non-usrmerged layout is not going to be supported, and thus
  37 some of its maintainers might not fix issues or intentionally remove
  38 non-usrmerged support, so you will need decide and pick your poison.
  39
  40 The program will perform the following overall actions:
  41
  42 =over
  43
  44 =item *
  45
  46 Check whether the system needs to be switched, otherwise do nothing,
  47
  48 =item *
  49
  50 Check for dpkg database consistency and otherwise abort.
  51
  52 =item *
  53
  54 Generate and install a regression prevention package, if requested on the
  55 command-line or otherwise on the prompt.
  56
  57 =item *
  58
  59 Get the list of files and alternatives that need to be restored.
  60
  61 =item *
  62
  63 Look for untracked kernel modules files that need to be moved too.
  64
  65 =item *
  66
  67 Create a shadow hierarchy under F</.usrunmess>, by creating the directories
  68 symlinks or hardlinking or copying the files as needed.
  69
  70 =item *
  71
  72 Prompt for confirmation before proceeding, if requested on the command-line.
  73
  74 =item *
  75
  76 Lock the dpkg database.
  77
  78 =item *
  79
  80 Mark all packages as half-configured to force running maintainer scripts
  81 that might need to recreate files.
  82
  83 =item *
  84
  85 Replace the aliased directories with the shadow ones, by creating a backup
  86 of the old symlinked directories and renaming the shadow ones over.
  87
  88 =item *
  89
  90 Relabel MAC information for directories and symlinks if necessary.
  91
  92 =item *
  93
  94 Remove backup symlinks.
  95
  96 =item *
  97
  98 Remove old moved objects, but defer directory removal.
  99
 100 =item *
 101
 102 Remove old deferred directories that are not referenced by dpkg-query.
 103
 104 =item *
 105
 106 Remove shadow root directory.
 107
 108 =item *
 109
 110 Register a B<policy-rc.d> to disallow service actions, which means that
 111 services might need to be restarted afterwards, ideally via a reboot.
 112
 113 =item *
 114
 115 Reconfigure all packages.
 116
 117 =item *
 118
 119 Unregister the B<policy-rc.d> and restore the alternatives state.
 120
 121 =back
 122
 123 B<Note>: When running the program from some shells such as L<bash(1)> or
 124 L<zsh(1)>, after executing it, you might need to request the shell to
 125 forget all remembered executable locations with for example C<hash -r>.
 126
 127 B<Note>: Some directories might linger after the migration in case they
 128 contain untracked files. A list is printed once the script has finished
 129 for further investigation.
 130
 131 B<Warning>: Note that this operation has the potential to render the system
 132 unusable or broken in case of a sudden crash or reboot, unexpected state of
 133 the system, or possible bugs in the script. Be prepared with recovery media
 134 and consider doing backups beforehand.
 135
 136 This program was introduced in dpkg 1.20.6.
 137
 138 =head1 OPTIONS
 139
 140 =over
 141
 142 =item B<-p>, B<--prompt>
 143
 144 Prompt at the time of no return, so that the debug output or the shadow
 145 hierarchy can be evaluated before proceeding.
 146
 147 =item B<--prevention>
 148
 149 =item B<--no-prevention>
 150
 151 Enables or disables generating and installing a regression prevention package
 152 into the system.
 153 If no option has been specified, the action to take will be prompted.
 154
 155 The generated package contains the B<Protected> field set to B<yes> to
 156 protect against accidental removal of the package.
 157
 158 =item B<-n>, B<--no-act>
 159
 160 =item B<--dry-run>
 161
 162 This option enables the dry-run mode, where no destructive action takes place,
 163 only the preparatory part.
 164
 165 =item B<-?>, B<--help>
 166
 167 Show the usage message and exit.
 168
 169 =item B<--version>
 170
 171 Show the version and exit.
 172
 173 =back
 174
 175 =head1 ENVIRONMENT
 176
 177 =over
 178
 179 =item B<DPKG_USRUNMESS_NOACT>
 180
 181 This setting defines whether to enable dry-run mode.
 182
 183 =back
 184
 185 =head1 SEE ALSO
 186
 187 L<https://wiki.debian.org/Teams/Dpkg/FAQ#broken-usrmerge>.