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 =head1 OPTIONS
 137
 138 =over
 139
 140 =item B<-p>, B<--prompt>
 141
 142 Prompt at the time of no return, so that the debug output or the shadow
 143 hierarchy can be evaluated before proceeding.
 144
 145 =item B<--prevention>
 146
 147 =item B<--no-prevention>
 148
 149 Enables or disables generating and installing a regression prevention package
 150 into the system.
 151 If no option has been specified, the action to take will be prompted.
 152
 153 The generated package contains the B<Protected> field set to B<yes> to
 154 protect against accidental removal of the package.
 155
 156 =item B<-n>, B<--no-act>
 157
 158 =item B<--dry-run>
 159
 160 This option enables the dry-run mode, where no destructive action takes place,
 161 only the preparatory part.
 162
 163 =item B<-?>, B<--help>
 164
 165 Show the usage message and exit.
 166
 167 =item B<--version>
 168
 169 Show the version and exit.
 170
 171 =back
 172
 173 =head1 ENVIRONMENT
 174
 175 =over
 176
 177 =item B<DPKG_USRUNMESS_NOACT>
 178
 179 This setting defines whether to enable dry-run mode.
 180
 181 =back
 182
 183 =head1 SEE ALSO
 184
 185 L<https://wiki.debian.org/Teams/Dpkg/FAQ#broken-usrmerge>.