Bug 218849

Summary: Remove rc.conf jail configuration via jail_* variables
Product: Base System Reporter: Joe Barbish <qjail1>
Component: confAssignee: FreeBSD bugs mailing list <freebsd-bugs>
Status: Open ---    
Severity: Affects Many People CC: 000.fbsd, brooks, current, erdgeist, grembo, imp, jamie, jamie, jonathan, julian, me, ngie, portmaster, rainer, thomas
Priority: --- Flags: ngie: mfc-stable9-
ngie: mfc-stable10-
ngie: mfc-stable11-
Version: CURRENT   
Hardware: Any   
OS: Any   

Description Joe Barbish 2017-04-24 15:17:09 UTC
In RELEASE 10.0 the following message first appeared and is issued for all jails configured in the rc.conf file. 

/etc/rc.d/jail: WARNING: Per-jail configuration via jail_* variables is 
obsolete.  Please consider migrating to /etc/jail.conf.


Four new RELEASES have been published since jail.conf became the intended method to use and the rc.conf jail configuration via jail_* variables method is still allowed.

I believe this is an oversight, its something that has fallen between the cracks and all but forgotten about. Four RELEASES is more than enough time for jail users and/or jail tools to make the move to the jail.conf method. 

It’s now time to remove the rc.conf jail configuration via jail_* variables method from the /etc/rc.d script set making jail.conf the only supported method.

Hopefully RELEASE 11.1 will see this implemented.
Comment 1 rainer 2017-04-24 17:54:46 UTC
My gut feeling is that this will break ezjail.

This chapter:

https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/jails-ezjail.html

would then have to be rewritten for iocage, qjail, cbsd, iocell....


Not sure if iocage has some sort of migration-strategy for ezjail-jails.
Comment 2 Miroslav Lachman 2017-04-24 18:45:42 UTC
I don't think anything in FreeBSD base should be driven / staled by lack o development in some external tools. Especially in case of jails - ezjail is not the only one or the best one. Ezjail is just one of many and there are much better tools with more features and compatible with jail.conf (modern way of maintaining jails)
Comment 3 rainer 2017-04-24 18:53:19 UTC
Fair enough.

But I believe the number of ezjail-jails is significant.

Also, as you can see, until now (11.0) it's the 3rd-party tool recommended by the FreeBSD project itself (if you take the mentioning in the handbook as an endorsement).

It's not a show-stopper for me - I'm just pointing it out.
Comment 4 Miroslav Lachman 2017-04-24 20:42:23 UTC
There is nothing special on jails created by ezjail so the configuration can be converted very easily. I have my own solution for jails with very similar structure and nullfs mount as ezjail and conversion from rc.conf to jails.conf takes few minutes.

I don't think ezjail is "recommended", it is documented and nobody has time to document any other tool. But that's another story.
It would be nice if somebody write chapter for another jail tools but as I am not using any of them I cannot help with this.

Or maybe there should not be 3rd party tools used in Handbook. There should be documented steps using tools in base and link to freshports to many 3rd party jail tools. Let the users choose.

This is very similar problem to portmaster / portupgrade tools - they are (were) used in Handbook but are not maintained well. They are lacking behind ports framework features and then some features are not easily implemented because ports team does not want to break things for these tools...
Comment 5 Chris Hutchinson 2017-04-25 03:49:05 UTC
(In reply to Miroslav Lachman from comment #4)
> Or maybe there should not be 3rd party tools used in Handbook. There should
> be documented steps using tools in base and link to freshports to many 3rd
> party jail tools. Let the users choose.
Can I simply add a plus one here?
I couldn't agree more on this. It seems very odd to me to read "FreeBSD" documentation. Only to have it explain how to use it through the use of 3rd party software. Isn't it supposed to teach new users how to use the features _provided by FreeBSD?
I see no reason not to touch lightly on 3rd party alternatives. But, honestly. Making the article primarily about 3rd party software is just wrong.
> 
> This is very similar problem to portmaster / portupgrade tools - they are
> (were) used in Handbook but are not maintained well. They are lacking behind
> ports framework features and then some features are not easily implemented
> because ports team does not want to break things for these tools...

Good example, Miroslav, and thanks! :-)
Comment 6 Michael Gmelin freebsd_committer 2017-04-25 11:00:52 UTC
Even though is not the project's responsibility and the fact that it's quite rusty, ezjail remains popular and breaking people's jails on a dot release sounds like a bad plan.
Comment 7 Joe Barbish 2017-04-25 15:02:29 UTC
In reply to comment # 3 which states

"But I believe the number of ezjail-jails is significant." 

This is un-true, since 10.0 was published many ezjail users have been moving to qjail because qjail uses jail.conf and its a fork of ezjail so the users are familiar with its operation  

"Also, as you can see, until now (11.0) it's the 3rd-party tool recommended by the FreeBSD project itself (if you take the mentioning in the handbook as an endorsement)."

This statement is also un-true. The FreeBSD project itself never publicly stated any position of 3rd-party tools. The inclusion of ezjail in the handbook is a current departure from the previous long held guild lines that no how-to-use details of 3rd-party tools would be contained in the handbook. A simple statement listing all the 3rd-party tools that may serve a certain function was allowable. The how-to-use details belong in the the 3rd-party tools manual pages.  


My comment.
With RELEASE 10.0 published 1/4/2014, jail.conf became the direction jails are headed. Any one who uses the rc.conf jail method even today gets the warning message telling them to convert to the jail.conf method. This warming has been in existence for 3+ years now. This warning message even shows up when ezjail starts its jails. Its not like the ezjail maintainer doesn't know about this. ezjail has had 2 updates since 1/4/2014 when RELEASE 10.0 was published, PR# 357253, committed 6/10/14, an upgrade from 3.3 to 3.4, and PR# 402477 committed 11/27/2015, an upgrade from 3.4 to 3.4.2. The internal design of ezjail still has not been changed to the jail.conf method. 3+ years has been more than enough time for ezjail to be upgraded to the jail.conf method if the maintainer so desired. 

Based on the replies, I see no reason to not remove the rc.conf jail definition method from the rc.d script set now. Further more this task should be made a priority so it gets accomplished for inclusion in 11.1.

At the same time the handbook ezjail section should be removed from the handbook being replaced with a simple informational statement listing all the 3rd-party jail tools, thus giving all of them fair and equal footing in the handbook.
Comment 8 Michael Gmelin freebsd_committer 2017-04-25 15:11:08 UTC
(In reply to Joe Barbish from comment #7)

As maintainer of sysutils/qjail you might look at this like it. I just know that we run hundreds of jails using ezjail and breaking that in anything but a major release would cause us major pain.

I agree that he best way would be to fix ezjail of course, but if the author doesn't feel like it, breaking it on a minor release will cause a lot of headache for users for no good reason.
Comment 9 Joe Barbish 2017-04-25 16:38:34 UTC
I see no benefit to dropping rc.conf jail support on a major release over a minor release. I both cases you are going to suffer the same consequences of NOT heeding the warning you have been getting for the past 3+ years. You should be taking this early warning to develop a migration to something else to limit your production down time. Stalling dropping rc.conf jail support is not a solution. You will have to face this sooner or later. 

If you feel this is too much for your environment, you could patch your copy of ezjail replacing rc.conf jail support with jail.conf support and post a PR.
Comment 10 Michael Gmelin freebsd_committer 2017-04-25 17:25:21 UTC
(In reply to Joe Barbish from comment #9)

I tried to give you feedback from real world installations and real world upgrade procedures, as you claimed ezjail isn't relevant any more.

Even though I agree that the compatibility should be dropped, I don't see the urgency in this matter and don't get why it can't wait for a major release - like, what is the downside of keeping compatibility until 12-RELEASE.
Comment 11 Conrad Meyer freebsd_committer 2017-04-25 17:53:44 UTC
(In reply to Joe Barbish from comment #9)
> I see no benefit to dropping rc.conf jail support on a major release over a minor release.

Breakage is expected in major releases; not in point releases.  It makes sense to hold off until a new major release.  There is no compelling reason this work needs to land before that.  It's simply removing functionality that worked in 11.0.
Comment 12 Ngie Cooper freebsd_committer 2017-04-25 18:22:00 UTC
For the sake of maintaining POLA, I recommend not breaking it on a dot-release and instead throw the switch on ^/head. I am very much in agreement there with grembo@.

I think it would be a great idea to patch ezjail if possible, mark it BROKEN otherwise. If marked BROKEN, this will either force folks to transition from ezjail to another solution, and/or the author to update ezjail to use jail.conf. We should document qjail  before doing that though so folks have a way to migrate to an alternate solution, if need be.
Comment 13 erdgeist 2017-04-25 21:50:34 UTC
(In reply to Ngie Cooper from comment #12)

Actually, I can not really see a benefit at all in removing that converter in base. It is not like the OS hands users of jail.conf like files a tool to properly create or modify them. Jamie's rewrite of jail(8) just broke editing jail configs for shell scripts. No big deal, as long as the OS keeps a compatibility until there ARE tools.

However, once you start taking these converters away from the base, it needs to be reimplemented in several ports, possibly leading to errors with each implementation.

If there would be a simple jail-admin tool allowing me operate on those complex structures from a script, or if there would be something like a jail.d with management scopes, where I'd be sure that configs are not manually touched, I would happily give up config in shell variables.

I also volunteered in getting stuff done, by adding code to jail(8) to extend the parser with config file management functionality, but Jamie used to be not as reponsive as I would've loved. If there's others wanting to review and possibly commit changes to the tool, I'd say that we go for it.
Comment 14 rainer 2017-04-25 22:04:29 UTC
I think the PTB (powers that be) ultimately decided that it's not in the interest of the project to have a tool and (and possibly an API) in base to create jails a la ezjail.

At least, that's my educated guess.

IIRC, iX-Systems uses (and sponsors) iocage (previously "warden").
Doubtlessly, other vendors/integrator have their own tools for managing jails - some may be in-house.
Maybe there was a tendency not to create too much overlapping functionality in the base-system.

It would be interesting to know if any of these vendors would be affected.

As such, maybe somebody can bring this up at the next dev/vendor-summit (which I assume to be at BSDCAN).
Comment 15 Mathieu Arnold freebsd_committer 2017-04-25 22:10:25 UTC
(In reply to Joe Barbish from comment #9)
> I see no benefit to dropping rc.conf jail support on a major release over a
> minor release. I both cases you are going to suffer the same consequences of
> NOT heeding the warning you have been getting for the past 3+ years. You
> should be taking this early warning to develop a migration to something else
> to limit your production down time. Stalling dropping rc.conf jail support
> is not a solution. You will have to face this sooner or later. 

There can be no dropping of features in minor releases. In the FreeBSD world, we call that POLA, for Principle of Least Astonishment.

If the jail_ variables are droppped, it will be for 12.0, or 13.0, but not on 11.1, or 10.4, or whatever.
Comment 16 Joe Barbish 2017-04-25 23:23:14 UTC
This is my objection to waiting for 12.0 before doing this. When 10.0 came out the removal of the rc.conf method was scheduled to happen at 11.0. Now 3+ years later 11.0 is out and the rc.conf method is still supported. Now your talking about waiting for 12.0 to remove the the rc.conf method. In 3-4 years this same problem will still not be fixed and again we will be talking about waiting for 13.0 to do it.

What you really talking about is holding up os deployment based on a 3rd-party tool. That's just plain crazy.

I purpose this solution. 
I believe that the /etc/rc.d/jail script is the single place where the current 11.0 system issues that warning message and processes the rc.conf method from. The removing of the rc.conf method will mean changing only that script. Someone else should verify this.

Inspecting the current version of the ezjail-admin script shows the start/stop commands launches a custom script /usr/local/etc/ezjail. After a bunch of grinding it finally launches /etc/rc.d/jail which does the actual start/stop work. This /etc/rc.d/jail script is part of the base os release.

Change the custom /usr/local/etc/ezjail script to launch /usr/local/etc/ezjail-jail instead of /etc/rc.d/jail. This is a one line change. Then populate the ezjail-jail script with the contents of the 11.0 /etc/rc.d/jail script. Make these changes to the port source and the corresponding changes to the port makefiles and bingo you have given ezjail the ability to internally use the rc.conf method for ever forward.

Now with this single show stopper fixed the removal of the rc.conf method can proceed to be scheduled for 11.1.
Comment 17 Brooks Davis freebsd_committer 2017-04-25 23:36:33 UTC
(In reply to Joe Barbish from comment #16)

As a project we DO NOT remove documented features from branches after the .0 release.  This sometimes mean we continue shipping a feature we had intended to remove as is the case for the jail_* variables.  It happens, we move remove it later and move on (I've removed code with decade "remove this soon" comments.

On top of existing policy, removing this compatibility has little value that I can see so we would cause harm to users for no real purpose.
Comment 18 Ngie Cooper freebsd_committer 2017-04-26 02:25:08 UTC
(In reply to Brooks Davis from comment #17)

The concern is still somewhat valid for 12.0-CURRENT. Reopening, but making it abundantly clear that this change will never, EVER, be MFCed.
Comment 19 Julian Elischer freebsd_committer 2017-04-26 12:23:53 UTC
I really really disagree that this bug should be acted upon

there are so many people out there who do a small numebr of simple jails in this way.

I think the bug shoudl just be closed.
Comment 20 Julian Elischer freebsd_committer 2017-04-26 12:26:00 UTC
previous comment shoudl have read "I strongly request that the bug be closed again".
Comment 21 Miroslav Lachman 2017-04-26 12:53:02 UTC
(In reply to Julian Elischer from comment #20)
Why? 
To miss the opportunity to remove deprecated code for the next major release again?
Then why we even put warnings to outdated code, ports and so on. 
If somebody that heavily depends on the old rc.d/jails behaviour then it should be moved to the ports... and maintained by somebody.
Comment 22 Warner Losh freebsd_committer 2017-04-26 13:41:30 UTC
Julian is saying that the code was deprecated by mistake. The functionality is useful and should remain, despite the warning. He's saying that even though we warned people the code was going away, it appears clear (to him at least) that we should retain this interface because it lowers the barrier to entry for jails when you have just a few.
Comment 23 Miroslav Lachman 2017-04-26 14:58:21 UTC
(In reply to Warner Losh from comment #22)
I think it turns in to bikeshed now. Are we talking about rc.conf variables to configure jails or about this as dependency for ezjail?

No matter if you have 1 or 5 or 20 jails. The configuration in jail.conf is as simple as in rc.conf, maybe even easier and more flexible.

## rc.conf style
jail_enable="YES"
jail_list="alpha"

jail_exec_start="/bin/sh /etc/rc"
jail_exec_stop="/bin/sh /etc/rc.shutdown"
jail_devfs_enable="YES"
jail_devfs_ruleset="devfsrules_jail"
jail_flags="-l -U root"

jail_alpha_rootdir="/vol0/jail/alpha"
jail_alpha_hostname="alpha.example.com"
jail_alpha_ip="10.11.12.13"


## jail.conf style
exec.start = "/bin/sh /etc/rc";
exec.stop  = "/bin/sh /etc/rc.shutdown";
exec.clean;
mount.devfs;
devfs_ruleset  = 4;
exec.jail_user = "root";

path            = "/vol0/jail/$name";
exec.consolelog = "/var/log/jail/$name.console";
mount.fstab     = "/etc/fstab.$name";

# A typical jail.
alpha {
	host.hostname = "alpha.example.com";
	ip4.addr = 10.11.12.13;
}


But if we are talking about jails management utility, then we have none in base but a lot in ports / packages that does not depend on rc.conf style.

We migrated all our jails on all machines from rc.conf to jail.conf the first time I have seen the warning after machine upgrade. It was really easy. 

I agree removing some feature on dot release can be a problem but I really don't understand why we should maintain two different styles for configuring jails in base.
Comment 24 Jamie Gritton freebsd_committer 2017-04-26 16:34:05 UTC
The easiest "fix" is certainly to remove the warning that the old method is going away.  I wouldn't quite call it "mistaken", but I'll (almost) agree there's no overriding need to take the bits out of rc.d/jail that translate the old shell variables.

Almost, because there are some confusing multiple paths on the kernel side that I'd would like to have deprecated, namely the security.jail.xxx_allowed and similar sysctls that used to be the only way to (globally) affect a lot of jail behavior, and are replaced by per-jail parameters but still live on as default values.  But I can't get rid of those because they're part of the old shell-based setup.

I remember some talk in the last year or two about a config file library that would allow (among other things) those DOS-like files that shell scripts seem to like.  What's the latest on that?  Jail.conf in particular had some sticking points as I recall.

Something like that could be enough for ezjail, though I also wouldn't mind of ezjail just started using the current jail.conf format.  Yes, it's harder for a shell script to use generally, but it would be possible to keep track of a shell-machine-readable version with a "hands off" comment at the top of it.
Comment 25 Thomas Steen Rasmussen / Tykling 2017-05-14 10:43:00 UTC
I believe the only reason the original poster insists on removing this now is to deliberately break ezjail, so people will switch to his qjail tool rather than stay with ezjail. Obviously this kind of behaviour does not belong here.

_Please_ keep the compatibility code in place until something else has been sorted.

To solve ezjails problem of jail.conf being difficult to manage from sh scripts erdgeist (ezjail author) offered to extend jail(8) with config file management capabilities earlier in this thread. I do suggest we take him up on the offer.
Comment 26 Miroslav Lachman 2017-05-15 08:15:48 UTC
(In reply to Thomas Steen Rasmussen / Tykling from comment #25)
Are you serious? Then why Joe provided the idea how to make ezjail survive this code removal?
Did you read the comment from Jamie?
Did you compare rc.d/jail with legacy support and without it? The legacy support is a mess compared to new style and some functionalities are missing.

As I already stated - ezjail is not the only one tool to manage jails and should not be used to take FreeBSD base as hostage. There are many alternatives and migration path is very trivial.
It's time to move on.
Comment 27 Jonathan Anderson freebsd_committer 2017-05-15 18:39:54 UTC
(In reply to Miroslav Lachman from comment #26)

> ezjail is not the only one tool to manage jails and should not be used
> to take FreeBSD base as hostage. There are many alternatives and migration
> path is very trivial.
>
> It's time to move on.

ezjail may not be the only jail management utility, but it's the only one in the Handbook. Before we "move on" from ezjail, perhaps the alternatives should be be documented in the same place?
Comment 28 Miroslav Lachman 2017-05-16 10:43:47 UTC
(In reply to Jonathan Anderson from comment #27)
I think the opposite way. Or we end up with the same problems as with ezjail, portupgrade, portmaster etc. now. Some features in base are stalled or very complicated just to not break 3rd party tools with no active maintainer. "because they are in Handbook"
It would be better to document jails with base tools and just some list of 3rd party tools with brief info about them and link to homepage of those projects.
Comment 29 Joe Barbish 2017-05-20 18:19:32 UTC
Today I submitted PR# 219421. This handbook patch removes all ezjail documentation from the handbook jail chapter and adds an political correct entry which is fair to all the jail management utilities in the port system as seen below. 


14.4.2. High-Level Administrative Tools in the FreeBSD Ports Collection

Manually creating and managing jails can quickly become tedious and error-prone. The ports collection contains some utilities designed to simplify jail management. Their listing here doesn't imply an recommendation or endorsement. Nothing more than a list of the different names of jail utilities in the ports sysutils category that you may want to review.

bsdploy, cbsd, ezjail, iocage, iocell, jail-primer, jailadmin, qjail, warden


The maintainer of ezjail has been provided a simple patch that removes ezjail's reliance on the conversion code in the /etc/rc.d/jail script thus clearing the way for this PR to move forward.