I'm guessing this just means documentation. I don't think additional tools are likely needed.

Could be. I guess the main thing is that it wasn't obvious. I was thinking to myself that all I had to do was clone libphutil, arcanist, and phabricator, repoint and bounce apache and then I'd be done.

And then people complained to me a few hours later that email wasn't being delivered.

And then a few hours later I realized that prototypes had been disabled.

I'm still not 100% confident that I successfully recovered all the settings.

Did you find and read this article?

https://secure.phabricator.com/book/phabricator/article/configuring_backups/

I'd not seen that, no. I knew there had to a config file, but I just kinda assumed it was really only for database credentials (and that everything else was in the db).

I assume that the other stuff is kept locally so that you don't have to hit the db for every action just to find base-uri, etc.? base-uri is fine because the web interface will warn you if it's not set, but it didn't occur to me that phabricator.show-prototypes or smtp-host might not be stored in db.

Local config is mostly local so that attackers who compromise administrator accounts can not escalate by adjusting config.

Settings like base-uri, show-prototypes and smtp-host allow an attacker to escalate an attack (for example: by changing the base URI to point at a server they control, activating prototypes which may have security vulnerabilities, or changing mail to be delivered through a server under their control) and may lead to compromise of an install. Web-adjustable configuration, like ui.header-color, does not allow an attacker to escalate.

I'll improve the documentation for this to specifically mention conf/local/local.json, but this stuff is basically already documented, and the document is the top hit on Google for me for "phabricator migrating to a new host" and similar terms, even in an incognito window, so I don't think there's much we could do to better surface it.

Gotcha.

What if the command-line tools just wrote them to the db instead of the local config file? They could still be uneditable in web UI to address admin compromise concerns. Might not be worth the effort though.

I agree, it's decently well-surfaced. Even better would be if it didn't have to surface (for people like me who mistakenly think they know what they're doing).

We can not write configuration like mysql.host into the database, because we need it in order to connect.

We may not be able to write configuration like load-libraries into the database, because external libraries may include code which runs before we establish a database connection.

It is generally desirable that secret keys are not present in the database, because this prevents an attacker with read-only SQL access from accessing them. The database exposes a lot more surface area than configuration settings do.

Although we currently read locked config from the database, I'd like to stop doing this in the future. This would limit the ability of an attacker who discovered an SQL injection hole giving them read/write access to fully compromise an install.

Broadly, when the two conflict, we value hardening Phabricator against compromise over making it easy to perform complex administrative tasks without reading the documentation.

We may provide something like a bin/backup export command in the future which writes a single export file to disk, although this would have some difficulty interacting with custom configuration files, and you'd probably have to read the documentation to learn about it (some related discussion in T7148).

Because this single file is likely to be enormously huge for many installs, I'm not sure it's especially valuable. It might be harder at the end of the day to work with an opaque 25GB "everything.gz" than a 1GB database dump + repositories + files (which can often be migrated transparently with S3 in larger setups).

Sounds reasonable, thanks.