1"use strict";(globalThis.webpackChunkpassbolt_docs||=[]).push([[1033],{97452(e,t,n){n.r(t),n.d(t,{assets:()=>c,contentTitle:()=>d,default:()=>m,frontMatter:()=>o,metadata:()=>a,toc:()=>l});const a=JSON.parse('{"id":"admin/resource-types/migrate-metadata","title":"Migrate Metadata","description":"Learn how to migrate metadata encryption in Passbolt","source":"@site/docs/admin/resource-types/migrate-metadata.mdx","sourceDirName":"admin/resource-types","slug":"/admin/resource-types/migrate-metadata","permalink":"/docs/admin/resource-types/migrate-metadata","draft":false,"unlisted":false,"editUrl":"https://github.com/passbolt/passbolt-docs/blob/main/docs/admin/resource-types/migrate-metadata.mdx","tags":[],"version":"current","lastUpdatedAt":1787883909000,"sidebarPosition":3,"frontMatter":{"title":"Migrate Metadata","description":"Learn how to migrate metadata encryption in Passbolt","sidebar_position":3},"sidebar":"adminGuideSidebar","previous":{"title":"Metadata Key","permalink":"/docs/admin/resource-types/metadata-key"},"next":{"title":"Allow Content Types","permalink":"/docs/admin/resource-types/allowed-content-types"}}');var i=n(74848),s=n(28453),r=n(42987);const o={title:"Migrate Metadata",description:"Learn how to migrate metadata encryption in Passbolt",sidebar_position:3},d="Migrate Metadata",c={},l=[{value:"Configuration Options",id:"configuration-options",level:2},{value:"Items to Migrate",id:"items-to-migrate",level:3},{value:"Migration Scope",id:"migration-scope",level:3},{value:"Important Considerations",id:"important-considerations",level:2},{value:"Migrating from the command line",id:"migrating-from-the-command-line",level:2},{value:"The tags command",id:"the-tags-command",level:3}];function h(e){const t={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,s.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(t.header,{children:(0,i.jsx)(t.h1,{id:"migrate-metadata",children:"Migrate Metadata"})}),"\n",(0,i.jsx)(t.p,{children:"This section enables administrators to migrate existing resource metadata from legacy cleartext format to encrypted format."}),"\n",(0,i.jsx)(r.A,{src:"/img/help/2025/06/migrate-metadata.png",alt:"Metadata migration interface",caption:"Metadata migration interface in Passbolt"}),"\n",(0,i.jsx)(t.h2,{id:"configuration-options",children:"Configuration Options"}),"\n",(0,i.jsx)(t.h3,{id:"items-to-migrate",children:"Items to Migrate"}),"\n",(0,i.jsx)(t.p,{children:"Toggle whether to include resource metadata in the migration. When enabled, the following fields will be encrypted:"}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsx)(t.li,{children:(0,i.jsx)(t.strong,{children:"Name"})}),"\n",(0,i.jsx)(t.li,{children:(0,i.jsx)(t.strong,{children:"Username"})}),"\n",(0,i.jsx)(t.li,{children:(0,i.jsx)(t.strong,{children:"URI"})}),"\n",(0,i.jsx)(t.li,{children:(0,i.jsx)(t.strong,{children:"Cleartext Description"})}),"\n"]}),"\n",(0,i.jsx)(t.p,{children:"If disabled, these fields remain in cleartext form. Passwords are always encrypted regardless of this setting."}),"\n",(0,i.jsx)(t.h3,{id:"migration-scope",children:"Migration Scope"}),"\n",(0,i.jsx)(t.p,{children:"Choose which types of resources to include in the migration:"}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"All content"})," - Includes both shared and personal resources."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"Shared content only"})," - Only shared resources are migrated."]}),"\n"]}),"\n",(0,i.jsx)(t.h2,{id:"important-considerations",children:"Important Considerations"}),"\n",(0,i.jsx)(t.p,{children:"Before initiating migration, ensure:"}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:["Encrypted metadata is enabled in ",(0,i.jsx)(t.a,{href:"/docs/admin/resource-types/encrypted-metadata",children:"Encrypted Metadata"})]}),"\n",(0,i.jsxs)(t.li,{children:["All users who need access to migrated resources have received the shared metadata key (see ",(0,i.jsx)(t.a,{href:"/admin/resource-types/metadata-key/",children:"Metadata Key"}),")"]}),"\n"]}),"\n",(0,i.jsx)(t.admonition,{title:"Best Practice",type:"tip",children:(0,i.jsx)(t.p,{children:"Always backup your database before migration. Metadata migration cannot be easily reversed."})}),"\n",(0,i.jsx)(t.admonition,{type:"warning",children:(0,i.jsx)(t.p,{children:"Migrating content to encrypted metadata might affect integrations that rely on accessing resource metadata in cleartext format."})}),"\n",(0,i.jsx)(t.h2,{id:"migrating-from-the-command-line",children:"Migrating from the command line"}),"\n",(0,i.jsxs)(t.p,{children:["Resources are migrated from the ",(0,i.jsx)(t.strong,{children:"Migrate Metadata"})," screen shown above. The commands that migrate resources and folders from the command line are registered on the server only when it runs in debug mode with the Selenium hooks active, so they are absent from a production install. The screen warns when the v4 to v5 upgrade is not allowed, a setting of the ",(0,i.jsx)(t.a,{href:"/docs/admin/resource-types/encrypted-metadata",children:"Encrypted Metadata"})," administration screen, and refuses to run only when no active metadata key is defined."]}),"\n",(0,i.jsx)(t.h3,{id:"the-tags-command",children:"The tags command"}),"\n",(0,i.jsxs)(t.p,{children:[(0,i.jsx)(t.code,{children:"passbolt metadata migrate_tags"})," is the one metadata command registered in production. It comes with the tags plugin, so it requires the Pro E
1dition, the Enterprise Edition, Business Cloud, Sovereign Cloud or Enterprise Cloud: the Community Edition has no tags plugin and no such command."]}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-bash",children:"passbolt metadata migrate_tags\n"})}),"\n",(0,i.jsxs)(t.p,{children:["Mind the command name: the ",(0,i.jsx)(t.code,{children:"metadata"})," group sits inside the ",(0,i.jsx)(t.code,{children:"passbolt"})," namespace, so the prefix is required. See ",(0,i.jsx)(t.a,{href:"/hosting/useful-commands/#running-commands",children:"Running Commands"})," for the full invocation on your installation type."]}),"\n",(0,i.jsxs)(t.p,{children:["The command is gated by a different setting from the one the screen uses, ",(0,i.jsx)(t.code,{children:"allow_creation_of_v5_tags"}),", and stops with this message when that setting is off:"]}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{children:'To enable, set "allow_creation_of_v5_tags" metadata settings to true via `update_metadata_types_settings` command.\n'})}),"\n",(0,i.jsxs)(t.p,{children:[(0,i.jsx)(t.code,{children:"allow_creation_of_v5_tags"})," is off in the default settings and no administration screen exposes a control for it, and ",(0,i.jsx)(t.code,{children:"update_metadata_types_settings"})," is itself one of the debug-only commands, so a production install does not have it either. The ",(0,i.jsx)(t.strong,{children:"Migrate Metadata"})," screen reports the tags migration status and warns on these settings, but it does not run the tags migration: this command is the route for tags."]}),"\n",(0,i.jsx)(t.admonition,{type:"caution",children:(0,i.jsxs)(t.p,{children:[(0,i.jsx)(t.code,{children:"migrate_tags"}),' exits with an error when there is no tag to migrate, which is worth knowing if you chain it in a script. Running it again over already migrated tags is not idempotent either: it reports "Tag ID ',0,' is already V5" for each of them and ends as a failed run. Read the migration status shown on this screen rather than running the command a second time.']})})]})}function m(e={}){const{wrapper:t}={...(0,s.R)(),...e.components};return t?(0,i.jsx)(t,{...e,children:(0,i.jsx)(h,{...e})}):h(e)}},42987(e,t,n){n.d(t,{A:()=>c});var a=n(86025),i=n(5556),s=n.n(i);const r="root_Qk78";var o=n(74848);const d=({src:e,alt:t,caption:n=null,size:i={}})=>{const s=(0,a.Ay)(e),d=i.width||i.height?{width:i.width,height:i.height}:{};return(0,o.jsxs)("figure",{className:r,children:[(0,o.jsx)("img",{src:s,alt:t,style:d}),n&&(0,o.jsx)("figcaption",{children:n})]})};d.propTypes={src:s().string.isRequired,alt:s().string.isRequired,caption:s().string,size:s().shape({width:s().oneOfType([s().string,s().number]),height:s().oneOfType([s().string,s().number])})};const c=d},28453(e,t,n){n.d(t,{R:()=>r,x:()=>o});var a=n(96540);const i={},s=a.createContext(i);function r(e){const t=a.useContext(s);return a.useMemo(function(){return"function"==typeof e?e(t):{...t,...e}},[t,e])}function o(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:r(e.components),a.createElement(s.Provider,{value:t},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.