The switch-to-configuration.pl logic is hard to follow and not really documented

[copumpkin]

I'm trying to figure out which variable I need to set if I don't want switch-to-configuration to stop my service. Poking around switch-to-configuration.pl, I find several variables that seem relevant, buried in a sea of nested conditionals in perl that make it rather hard to figure out when it makes sense to use each variable.

Here's a few of those variables:

• X-StopOnRemoval
• X-StopOnReconfiguration
• X-ReloadIfChanged
• X-RestartIfChanged
• X-StopIfChanged
• RefuseManualStop
• RefuseManualStart

It also seems like the suggested possible "space of variation" of these variables is larger than you'll actually benefit from. For example, eyeballing the logic, it seems like setting X-ReloadIfChanged means that X-RestartIfChanged, RefuseManualStop, and X-StopIfChanged will be ignored.

Not fully understanding the logic enough to have a strong opinion on this, it seems at first glance like some of those variables would be easier to follow if they turned into e.g., X-ActionIfChanged (which could take on values like Reload, Restart, or Stop). Either way I'm still having trouble distinguishing semantic differences between "changed" and "reconfiguration".

cc @edolstra

[mmahut]

Any news on this issue?

[aanderse]

@mmahut it seems like someone just needs to dig into the source, figure it out, and then write some documentation I guess.

[stale]

Hello, I'm a bot and I thank you in the name of the community for opening this issue.

To help our human contributors focus on the most-relevant reports, I check up on old issues to see if they're still relevant. This issue has had no activity for 180 days, and so I marked it as stale, but you can rest assured it will never be closed by a non-human.

The community would appreciate your effort in checking if the issue is still valid. If it isn't, please close it.

If the issue persists, and you'd like to remove the stale label, you simply need to leave a comment. Your comment can be as simple as "still important to me". If you'd like it to get more attention, you can ask for help by searching for maintainers and people that previously touched related code and @ mention them in a comment. You can use Git blame or GitHub's web interface on the relevant files to find them.

Lastly, you can always ask for help at our Discourse Forum or at #nixos' IRC channel.

[aanderse]

At some point @flokli had interest on this topic, but I'm not sure what the situation is now. This issue is still relevant, though.

[flokli]

Yeah, I did some digging in May on this, and came up with this:

#49528 (comment)

I didn't find the time to change anything in the script, though.

[aanderse]

I still think there is value in having the ability to express changes which require a reload and changes that require a restart. With httpd, for example, if you modify the extraModules option this requires a restart, and most other changes a reload is sufficient.

[stale]

I marked this as stale due to inactivity. → More info

[flokli]

still relevant.

[stale]

I marked this as stale due to inactivity. → More info

[stale]

I marked this as stale due to inactivity. → More info

[flokli]

@dasJ @ajs124 wasn't there now more documentation on this?

[ajs124]

Are you referring to https://nixos.org/manual/nixos/unstable/index.html#sec-switching-systems?

[dasJ]

Yeah, that's what I wrote. It's only on unstable for now

[flokli]

I think we should link from the top of switch-to-configuration.pl to the docs, and explain behaviour is documented there - maybe just a "look in the NixOS manual, section …", and then this issue can be closed.

The main idea is that people looking at the perl script know where to find the behaviour documentation.