Project

General

Profile

Bug #56364

Improve error messages that display when the iocage defaults.json file is missing or corrupt

Added by Timothy Moore II 5 months ago. Updated 2 months ago.

Status:
Done
Priority:
No priority
Assignee:
Aaron St. John
Category:
Documentation
Target version:
Seen in:
Severity:
Low
Reason for Closing:
Reason for Blocked:
Needs QA:
No
Needs Doc:
No
Needs Merging:
No
Needs Automation:
No
Support Suite Ticket:
n/a
Hardware Configuration:
ChangeLog Required:
No

Description

Opened at Warren's suggestion, seen in https://github.com/freenas/iocage/pull/74/files:

1. The error message that displays when the iocage defaults.json file is missing reads: "Default configuration missing, creating one". Suggested rework: "[/mnt/pool1/iocage/]: defaults.json file is missing. Creating new defaults.json file with standard jail settings."
Replace [] with the actual path to the iocage dataset that is missing defaults.json.

2. The error message that displays when the iocage defaults.json file is corrupted reads: "Defaults are corrupt, using iocage defaults in memory". The message should communicate where the corrupt file is located and one option to resolve the error.
Suggested rework: "Jail default settings from [/mnt/pool1/iocage/defaults.json] are corrupt. Jail is created with iocage default settings from memory. Delete [/mnt/pool1/iocage/defaults.json] for iocage to recreate the file with working defaults."

Replace [] with the actual path to the corrupted file.

History

#1 Updated by Dru Lavigne 5 months ago

  • Assignee changed from Release Council to William Grzybowski

#2 Updated by William Grzybowski 5 months ago

  • Assignee changed from William Grzybowski to Brandon Schneider
  • Target version changed from 11.2-U2 to Backlog
  • Severity changed from New to Low

#3 Updated by Brandon Schneider 5 months ago

  • Status changed from Unscreened to Closed
  • Reason for Closing set to Not to be fixed

The defaults file always lives in one location. So displaying it for that error message is redundant. Furthermore, there can only be one pool activated at one time, and mountpoints can get quite long. So there isn’t a mystery where the file lives.

It’s meant to be a quick message alerting the user, and the suggestion reads like a novel. We have a lot of iocage users who are not native English speakers and complain about length of messages and having trouble parsing them due to length. This message was chosen as it’s short and to the point.

The user changed these defaults, hence the corruption. They know where they are, what they did and that they can remove them to fix it as they never created it in the first place, iocage creates it and they are aware.

tldr ; No :)

#4 Updated by Warren Block 5 months ago

Brandon Schneider wrote:

The defaults file always lives in one location. So displaying it for that error message is redundant. Furthermore, there can only be one pool activated at one time, and mountpoints can get quite long. So there isn’t a mystery where the file lives.

Except that assumes knowledge of how iocage works and which dataset is the iocage dataset. We spent some time yesterday working it out, and an appliance user will have much more difficulty.

It’s meant to be a quick message alerting the user, and the suggestion reads like a novel. We have a lot of iocage users who are not native English speakers and complain about length of messages and having trouble parsing them due to length. This message was chosen as it’s short and to the point.

There are two messages. A message indicating a needed file was recreated does not need to tell the user where it is. One that complains about the file being corrupted certainly should. Otherwise it is not useful, essentially a "Something is wrong" message. As far as length, we would be happy to work with you on wording, as part of our responsibility is to make sure error messages are clear, informative, and give the user some idea of how to solve the problem or where to go next.

The user changed these defaults, hence the corruption. They know where they are, what they did and that they can remove them to fix it as they never created it in the first place, iocage creates it and they are aware.

If the user changed it, maybe they remember where that file is. Maybe it was corrupted by a data error. Either way, giving them a path to the file makes locating it simple. Telling them they can fix the corruption by deleting the file and letting iocage create it is even better, giving them a way to fix their problem directly.

Beyond all this, every time a clear message eliminates a support call, it reduces time and aggravation on the part of both the user and the support department.

#5 Updated by Brandon Schneider 5 months ago

Except that assumes knowledge of how iocage works and which dataset is the iocage dataset. We spent some time yesterday working it out, and an appliance user will have much more difficulty.

Except you guys didn't work it out, I explained the whole process to Tim in pm. It's a very simple and clear procedure that is intuitive enough imo that it does not require a paragraph of explanation.

There are two messages. A message indicating a needed file was recreated does not need to tell the user where it is. One that complains about the file being corrupted certainly should. Otherwise it is not useful, essentially a "Something is wrong" message. As far as length, we would be happy to work with you on wording, as part of our responsibility is to make sure error messages are clear, informative, and give the user some idea of how to solve the problem or where to go next.
If the user changed it, maybe they remember where that file is. Maybe it was corrupted by a data error. Either way, giving them a path to the file makes locating it simple. Telling them they can fix the corruption by deleting the file and letting iocage create it is even better, giving them a way to fix their problem directly.

Beyond all this, every time a clear message eliminates a support call, it reduces time and aggravation on the part of both the user and the support department.

So we can clear up some confusion here. Firstly, appliance users aren't the ones this message is aimed at. It's the FreeBSD and more advanced users. The appliance users use the GUI. Where we are free to have beautifully verbose and long messages as we aren't concerned about overflowing the console (users use serial, sticking to small messages ~79 characters is what iocage aims to achieve)

Secondly, while a user may not be told the path, the user iocage is aimed at will go to the iocage mount location and instantly notice the defaults.json. It's implied, and does not explicitly need to be told.

Lastly this doesn't save time or aggravation for the support department. As iocage is not officially supported on the CLI. It is supported through the GUI. And since the GUI does not provide a way to change defaults, the users wouldn't be exposed to this. If filesystem corruption happened, iocage would use the defaults in memory and the GUI users would be none the wiser, unless they went to the CLI. In which case see the advanced users explanation above. We shouldn't be encouraging appliance users to use the CLI until we have no choice (to rule out a MW/GUI bug and see if the behavior works for them the 'standard' way). So this message wouldn't be that useful to those users, as they aren't aware of what rm is, and iocage isn't a remedial shell learning experience. It's a jail manager. You are expected to know how to work your way around a shell if an issue comes up, and this includes locating that file with the many means the shell provides you. So the way I see it, providing the users a path is not going to solve the confusion, but instead have the users who shouldn't be messing around in the CLI ask "How do I remove that file?" with a million duplicate tickets asking that exact question. Let's keep GUI users in the GUI and advanced users in the CLI, they know what they need to do.

Anything iocage related outside of the GUI has always been described as 'At Your Own Risk', and it continues to be our message. That won't change, we have our GUI team spending all their energy making a robust GUI for them to use for a reason, let's not confuse our target audiences when we have message suggestions.

Length of messages in iocage is something I care about a lot, as I am the one who has to field the users who complain about them in iocage's tracker. So, I appreciate the suggestion, but as the BDFL of iocage, once again the answer is no.

#6 Updated by Brandon Schneider 5 months ago

  • Needs Doc changed from Yes to No
  • Needs Merging changed from Yes to No

#7 Updated by Brandon Schneider 5 months ago

  • Private changed from No to Yes

Setting this ticket to private as it's just us squabbling :)

#8 Updated by Brandon Schneider 5 months ago

  • Category changed from Middleware to Documentation
  • Status changed from Closed to Unscreened
  • Assignee changed from Brandon Schneider to Warren Block
  • Reason for Closing deleted (Not to be fixed)
  • Needs Doc changed from No to Yes
  • Needs Merging changed from No to Yes

Throwing ticket to Warren per discussion with Dru. The requirements being no paths in the message, 79 characters max, and not multiple lines.

#9 Updated by Warren Block 5 months ago

Suggested:

defaults.json in /mnt/pool1/iocage/ corrupted (delete to recreate), using memory values.

#10 Updated by Warren Block 5 months ago

  • Assignee changed from Warren Block to Brandon Schneider

#11 Updated by Warren Block 5 months ago

  • Assignee changed from Brandon Schneider to Aaron St. John

#12 Updated by Dru Lavigne 5 months ago

  • Target version changed from Backlog to 11.2-RELEASE
  • Seen in set to 11.2-RC2

#13 Updated by Dru Lavigne 5 months ago

  • Private changed from Yes to No

#14 Updated by Aaron St. John 5 months ago

  • Status changed from Unscreened to In Progress
  • Needs Doc changed from Yes to No

#15 Updated by Aaron St. John 5 months ago

  • Status changed from In Progress to Ready for Testing
  • Needs Merging changed from Yes to No

#18 Updated by Bonnie Follweiler 5 months ago

  • Status changed from Ready for Testing to Passed Testing

#20 Updated by Dru Lavigne 5 months ago

  • Status changed from Passed Testing to Failed Testing

#22 Updated by Dru Lavigne 5 months ago

  • Status changed from Failed Testing to In Progress
  • Target version changed from 11.2-RELEASE to 11.2-U2

#23 Updated by Aaron St. John 4 months ago

(error message change) freenas/11.2-stable branch PR: https://github.com/freenas/iocage/pull/157

#24 Updated by Dru Lavigne 3 months ago

  • Status changed from In Progress to Ready for Testing

#26 Updated by Jeff Ervin 2 months ago

53850

See screenshot. Error message is correct...but is it supposed to create the jail? Just verifying before I pass it.

#27 Updated by Brandon Schneider 2 months ago

Yes :)

#28 Updated by Jeff Ervin 2 months ago

  • Status changed from Ready for Testing to Passed Testing
  • Needs QA changed from Yes to No

FreeNAS-11.2-U2-INTERNAL86

#29 Updated by Dru Lavigne 2 months ago

  • Status changed from Passed Testing to Done

Also available in: Atom PDF