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.
  34 See the dpkg FAQ.
  35
  36 B<Note>: In Debian its tech-ctte has decreed that on the release after
  37 bookworm the non-usrmerged layout is not going to be supported, and thus
  38 some of its maintainers might not fix issues or intentionally remove
  39 non-usrmerged support, so you will need decide and pick your poison.
  40
  41 The program will perform the following overall actions:
  42
  43 =over
  44
  45 =item *
  46
  47 Check whether the system needs to be switched, otherwise do nothing,
  48
  49 =item *
  50
  51 Check for dpkg database consistency and otherwise abort.
  52
  53 =item *
  54
  55 Generate and install a regression prevention package, if requested on the
  56 command-line or otherwise on the prompt.
  57
  58 =item *
  59
  60 Get the list of files and alternatives that need to be restored.
  61
  62 =item *
  63
  64 Look for untracked kernel modules files that need to be moved too.
  65
  66 =item *
  67
  68 Create a shadow hierarchy under F</.usrunmess>, by creating the directories
  69 symlinks or hardlinking or copying the files as needed.
  70
  71 =item *
  72
  73 Prompt for confirmation before proceeding, if requested on the command-line.
  74
  75 =item *
  76
  77 Lock the dpkg database.
  78
  79 =item *
  80
  81 Mark all packages as half-configured to force running maintainer scripts
  82 that might need to recreate files.
  83
  84 =item *
  85
  86 Replace the aliased directories with the shadow ones, by creating a backup
  87 of the old symlinked directories and renaming the shadow ones over.
  88
  89 =item *
  90
  91 Relabel MAC information for directories and symlinks if necessary.
  92
  93 =item *
  94
  95 Remove backup symlinks.
  96
  97 =item *
  98
  99 Remove old moved objects, but defer directory removal.
 100
 101 =item *
 102
 103 Remove old deferred directories that are not referenced by dpkg-query.
 104
 105 =item *
 106
 107 Remove shadow root directory.
 108
 109 =item *
 110
 111 Register a B<policy-rc.d> to disallow service actions, which means that
 112 services might need to be restarted afterwards, ideally via a reboot.
 113
 114 =item *
 115
 116 Reconfigure all packages.
 117
 118 =item *
 119
 120 Unregister the B<policy-rc.d> and restore the alternatives state.
 121
 122 =back
 123
 124 B<Note>: When running the program from some shells such as L<bash(1)> or
 125 L<zsh(1)>, after executing it, you might need to request the shell to
 126 forget all remembered executable locations with for example C<hash -r>.
 127
 128 B<Note>: Some directories might linger after the migration in case they
 129 contain untracked files.
 130 A list is printed once the script has finished
 131 for further investigation.
 132
 133 B<Warning>: Note that this operation has the potential to render the system
 134 unusable or broken in case of a sudden crash or reboot, unexpected state of
 135 the system, or possible bugs in the script.
 136 Be prepared with recovery media
 137 and consider doing backups beforehand.
 138
 139 This program was introduced in dpkg 1.20.6.
 140
 141 =head1 OPTIONS
 142
 143 =over
 144
 145 =item B<-p>, B<--prompt>
 146
 147 Prompt at the time of no return, so that the debug output or the shadow
 148 hierarchy can be evaluated before proceeding.
 149
 150 =item B<--prevention>
 151
 152 =item B<--no-prevention>
 153
 154 Enables or disables generating and installing a regression prevention package
 155 into the system.
 156 If no option has been specified, the action to take will be prompted.
 157
 158 The generated package contains the B<Protected> field set to B<yes> to
 159 protect against accidental removal of the package.
 160
 161 =item B<-n>, B<--no-act>
 162
 163 =item B<--dry-run>
 164
 165 This option enables the dry-run mode, where no destructive action takes place,
 166 only the preparatory part.
 167
 168 =item B<-?>, B<--help>
 169
 170 Show the usage message and exit.
 171
 172 =item B<--version>
 173
 174 Show the version and exit.
 175
 176 =back
 177
 178 =head1 ENVIRONMENT
 179
 180 =over
 181
 182 =item B<DPKG_USRUNMESS_NOACT>
 183
 184 This setting defines whether to enable dry-run mode.
 185
 186 =back
 187
 188 =head1 SEE ALSO
 189
 190 L<https://wiki.debian.org/Teams/Dpkg/FAQ#broken-usrmerge>.