chef-boneyard / chef-web-docs-2016 Goto Github PK

James,

I discovered some interesting helper methods to change recipe behavior based on Windows version.

You can write a recipe with code like this:

require 'chef/win32/version'

win_version = Chef::ReservedNames::Win32::Version.new

Now this win_version object has useful methods like

:windows_8_1?
:windows_server_2012_r2?
:windows_8?
:windows_server_2012?
:windows_7?
:windows_server_2008_r2?
:windows_server_2008?
:windows_vista?
:windows_server_2003_r2?
:windows_home_server?
:windows_server_2003?
:windows_xp?
:windows_2000?

As well as:

:marketing_name

(which returns the product string e.g. “Windows 2012 Server”)

And also:

:cluster?
:core?
:datacenter?

For the various types of Windows installation.

Thought that might be useful in the docs somewhere.

The "Bootstrap a Node" page borrows the description from the "About the Server" page. Consequently, the lead paragraph discusses a separate topic. This lead paragraph should be more tailored to the title.

The page also says that if you are using a non-Ubuntu OS for your node, you need to provide other info to the bootstrap command, but gives no examples or the proper syntax. The page should list what OSes are supported and the proper syntax,

or point to a page that does.

See attached screenshot and comments.

No mention of it here: http://docs.opscode.com/install_workstation.html

The docs http://docs.opscode.com/resource_registry_key.html state that :string is the default type for registry keys, but leaving this off in recipe code doesn't work. Given recipe code:

registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\OEMInformation' do
  values [{:name => 'Logo', :data => 'C:\Windows\System32\oemlogo.bmp'},
          {:name => 'Manufacturer', :data => node['windowshacks']['oeminfo']['manufacturer']},
          {:name => 'SupportHours', :data => node['windowshacks']['oeminfo']['supporthours']},
          {:name => 'SupportPhone', :data => node['windowshacks']['oeminfo']['supportphone']},
          {:name => 'SupportURL', :data => node['windowshacks']['oeminfo']['supporturl']}]
  action :create
end

the following stack trace is seen:

ArgumentError: Missing type key in RegistryKey values hash
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/resource/registry_key.rb:57:in `block in values'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/resource/registry_key.rb:55:in `each'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/resource/registry_key.rb:55:in `values'
c:/chef/cache/cookbooks/windowshacks/recipes/oeminfo.rb:30:in `block in from_file'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/dsl/recipe.rb:71:in `instance_eval'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/dsl/recipe.rb:71:in `method_missing'
c:/chef/cache/cookbooks/windowshacks/recipes/oeminfo.rb:25:in `from_file'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/mixin/from_file.rb:30:in `instance_eval'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/mixin/from_file.rb:30:in `from_file'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/cookbook_version.rb:237:in `load_recipe'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/run_context.rb:151:in `load_recipe'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/run_context/cookbook_compiler.rb:139:in `block in compile_recipes'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/run_context/cookbook_compiler.rb:137:in `each'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/run_context/cookbook_compiler.rb:137:in `compile_recipes'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/run_context/cookbook_compiler.rb:74:in `compile'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/run_context.rb:86:in `load'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/client.rb:249:in `setup_run_context'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/client.rb:492:in `do_run'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/client.rb:212:in `run'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/application/windows_service.rb:169:in `run_chef_client'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/application/windows_service.rb:95:in `block in service_main'
<internal:prelude>:10:in `synchronize'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/application/windows_service.rb:75:in `service_main'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/application/windows_service.rb:286:in `mainloop'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/application/windows_service.rb:286:in `mainloop'
C:/opscode/chef/embedded/lib/ruby/gems/1.9.1/gems/chef-11.6.0/lib/chef/application/windows_service.rb:286:in `<main>'

I'll leave it to @adamedx or @sersut to determine if the provider code should be changed to actually default to :string if no type is passed but in the interim the docs should be updated.

The server types page here needs to be updated with the new product names for Hosted and Private Chef: http://docs.opscode.com/server_types.html

I'd do this myself except the icons need to be updated too.

It's not clear from the metadata.rb page whether the attribute for the license should be "licensing" or "license" and if the parameter value is free-form or should be chosen from a list of licensing codes.

See attached for comments.

This is the opening to the apt_package resource explanation and seems to be misplaced as it is very general (http://docs.opscode.com/chef/resources.html#apt-package)

"A resource is a key part of a recipe that defines the actions that can be taken against a piece of the system. These actions are identified during each Chef run as the resource collection is compiled. Once identified, each resource (in turn) is mapped to a provider, which then configures each piece of the system."

The current docs.opscode.com index page doesn't link to release notes for older versions of Chef, only the last major/minor version prior to the current one. If I want to find the release notes for 11.4.x for instance I have to go to the 11.6.x page.

This paragraph in https://github.com/opscode/chef-docs/blob/master/includes_repository/includes_repository.rst is odd to me. Seems out of place, too specific, and not suited to general documentation. It assumes the repository is on github, etc.

"The Chef repository can be cloned directly from github or it can be downloaded from github as a tar.gz file, and then associated with another version source control system, such as Subversion, Mercurial, or Bazaar."

Per the discussion with support, the current release of Reporting (1.0.0) will not work in HA or tiered setups. I found this out the hard way.

Docs does not have a documentation for writing own Providers.
For example, new_resource, current_reource, load_current_resource,
updated_by_last_action, whyrun_supported, converge_by...
They are needed to write proper Providers.
Would you provide their documentation and some examples?

http://docs.opscode.com/essentials_data_bags_encrypt.html

It's at the last code block.

Hi @jamescott and other committers,

There's a bunch of open issues and pull requests sitting around here, not getting any love.

It's considered good form to at least comment on them, provide some feedback to the author as to why you have not yet merged in their contribution that they took the time to write.

If you need some help reviewing and validating these, by all means, ask for help. We're a community, and together we are strong.

-M

in in swaps/swap_names.txt,

.. |crond| replace:: cron.d

in step_resource/step_resource_service_use_variable.rst,

The following example shows how to install |crond|
how to install |crond| on various nodes
the |crond| service on nodes

they "crond" are just "crond" program, not "cron.d" directory.

http://wiki.opscode.com/display/chef/Shef probably just needs to be ported over

http://docs.opscode.com/config_rb_chef_server.html

a lot of descriptions has only "Default value" without real descriptions.
so i do not understand and explain what settings mean.

If I

directory MY_DIR do
  user USER
end

What is the mode? This is missing from the docs.

See attached image for the typos.

Workstation install step (http://docs.opscode.com/install_workstation.html)

Download .pem files and knife.rb

[ This step is not required for the open source Chef Server ]
...

Where are they for the open source Chef Server? Where does one get them? Login to the web UI and generate a new private key for the 'chef-validator' client? Needs docs.

This page: http://docs.opscode.com/chef/essentials_cookbook_recipes.html

States: "A recipe... May be tagged to facilitate the creation of arbitrary groupings that exist outside of the normal naming conventions an organization may have"

I've never heard of a recipe being tagged. Don't we mean that nodes can be tagged?

The words "file specificity" on http://docs.opscode.com/resource_template.html should link to http://docs.opscode.com/essentials_cookbook_files_specificity.html

The "$" prompt makes it seem like folks don't need root privileges to run these commands, but they do. So maybe either say "sudo", or change the prompt to a "#"?

Examples of such commands:

• opscode-push-jobs-server-ctl [whatever]
• private-chef-ctl [whatever]

http://docs.opscode.com/essentials_handlers.html

doesn't mention that start handlers are also available.

Actually the chef_handler cookbook needs to be updated to allow them too.

Per discussion in HipChat, Chef 11.x no longer uses Moneta to do the local cookbook caching, so the "cache_type" directive in knife.rb (and client.rb) is deprecated.

http://docs.opscode.com/config_rb_knife.html (and friends)

In addition, reading the code, there seems to be a syntax_check_cache_path directive that will be used in preference to the old [:cache_options][:path] setting:

https://github.com/opscode/chef/blob/11.4.4/lib/chef/cookbook/syntax_check.rb#L53

This should be reflected in the documentation as well.

http://docs.opscode.com/resource_package.html

package "name" do
  attribute "value" # see attributes section below
  ...
  action :action
end

The above syntax description confuses me, because there is no attribute named attribute.
I believe that attribute should be replaced with some_attribute or actual attribute.

The cookbook metadata page, http://docs.opscode.com/essentials_cookbook_metadata.html , describe the settings that can be present in a metadata.rb, but fail to make it clear that most of them do not affect the operation of chef-client/chef-solo in any way.

As a particular example, someone in IRC asked why a chef-client node was trying to compile a cookbook in his run_list, when it's "support" metadata indicated that it wasn't supported on that node's platform.

The cookbook metadata page should clearly indicate which settings are optional/informational (used only by the community cookbook site), and which affect chef-solo/chef-client's operation.

I think a lot of people's lives would be improved if there were a single page in the documentation with all of the resource usage examples from the rest of the docs as a quick reference. It would be in alphabetical order, and could be searched with command-s. The available actions and a link to the more detailed resource documentation would be supplied alongside it.

This operator is more accurately named "pessimistic greater than" and the docs should explain its behavior in more detail as most won't be familiar with the semantics of RubyGems.

"Restart when a configuration is broken" block in http://docs.opscode.com/chef/resources.html makes no sense

My question on serverfault:
http://serverfault.com/questions/471911/in-the-chef-resource-document-why-do-they-have-parenthesis-around-the-name-in-t/471930#471930

File in question:
https://github.com/opscode/chef-docs/blob/master/step_resource/step_resource_execute_command_from_template.rst

The file includes_plugin_knife/includes_plugin_knife_azure_certificate.rst has outdated information with respect to operating the Knife Azure plugin.

It is no longer necessary to use openssl contortions to get the plugin to talk to Azure. Instead, the "publishsettings" file can be used directly by knife azure, either by setting:

knife[:azure_publish_settings_file] = "/path/to/your.publishsettings"

or by passing --azure-publish-settings-file as a parameter to any knife azure command.

When looking at the docs site, it is not obvious how to report problems with the content. There is no obvious link to this repo on Github, nor any other advice on reporting issues (Github Issues? Opscode Tickets? Mailing list?)

As someone participating on IRC/mailing list,
When another user reports unclear/misleading information on the docs site,
I would like to be able to point them at a howto for reporting that problem.

When installing Push Jobs into a HA Enterprise Chef environment, port 10003 needs to be open on both back ends to the front end servers for the API calls to be passed through.

This isn't documented anywhere at the moment, but should probably go along with the documentation here: Install Push Jobs

Why do the encrypted databag docs suggest using openssl rand for key generation when OpenSSL already ships with proper key management tools? A random sequence of bits isn't quite as secure as a proper key, is it? I've tested proper keys with encrypted data bags and they still work, so I can't imagine why the docs aren't pointing people at using proper keys.

The words "file specificity" on http://docs.opscode.com/resource_cookbook_file.html should link to http://docs.opscode.com/essentials_cookbook_files_specificity.html

"Docs for Current Versions: ... Ohai 7"

Ohai 7 is a pre-release and can't actually be used by normal users. It shouldn't be referred to as the current version and http://docs.opscode.com/ohai.html should not reference it. Any docs for Ohai 7 should have very large warning banners that it is a pre-release.

In the examples at http://docs.opscode.com/resource_directory.html#windows-file-security the example:

rights :full_control, "user_name", option => :applies_to_children

should in fact be:

rights :full_control, "user_name", :applies_to_children => true

Query: https://twitter.com/jpluscplusm/status/436838417666953216

Example: https://gist.github.com/jtimberman/1e9ec15c2d972be29987

Applies to "package" if the provider is apt, or "apt_package" specifically.

Hi,

I have a request, I want your feedback on these, I can write it then :

On this section, I think it could be a good idea to do distinction between :

• first/admin install -> admin workstation (with admin.pem, and rights to create other users)
• user install -> the admin create a knife.rb and a USER.pem and the user install it

What do you think about it?

Also, for the first install, What is the best?

• configure knife on the server (like it is in the wiki right now)
• configure knife on the workstation : (like in this blog post )

Hi,

I did this little tutorial to install OSS chef server 11 on debian. It's a bit hacky but it's working, if you are interested, I can write a documentation page here :)

Let me know!

In a README at
git clone https://github.com/myusername/chef-docs.git
there should be "opscode" instead of "myusername", I suppose.

We have a page at http://docs.opscode.com/lwrp_windows.html that documents the windows_package resource, but it is missing some options with respect to the documentation on GitHub. The full list of supported attributes is:

    package_name: name attribute. The 'DisplayName' of the application installation package.
    source: The source of the windows installer. This can either be a URI or a local path.
    installer_type: They type of windows installation package. valid values are: :msi, :inno, :nsis, :wise, :installshield, :custom. If this value is not provided, the provider will do it's best to identify the installer type through introspection of the file.
    checksum: useful if source is remote, the SHA-256 checksum of the file--if the local file matches the checksum, Chef will not download it
    options: Additional options to pass the underlying installation command
    timeout: set a timeout for the package download (default 600 seconds)
    version: The version number of this package, as indicated by the 'DisplayVersion' value in one of the 'Uninstall' registry keys. If the given version number does equal the 'DisplayVersion' in the registry, the package will be installed.
    success_codes: set an array of possible successful installation return codes. Previously this was hardcoded, but certain MSIs may have a different return code, e.g. 3010 for reboot required. Must be an array, and defaults to [0, 42, 127].

step_resource/step_resource_service_stop_do_stuff_start.rst and step_resource/step_resource_mount_mysql.rst have almost same content (the latter maybe have typo).

BTW, chef_master/source/resource_service.rst, chef_master/source/resource_execute.rst and chef_master/source/resource_mount.rst include both step_resource/step_resource_service_stop_do_stuff_start.rst and step_resource/step_resource_mount_mysql.rst.

So, step_resource/step_resource_mount_mysql.rst is just redundant or need to update?

The first paragraph on the "Manage the Hosted Chef Server Page" is repeated.

http://docs.opscode.com/manage_server_hosted.html

See screenshot below.

I think the docs for 'depends' should be clarified further.

[14:39] So 'depends' in metadata.rb does not do anything other than require that the depended-upon cookbook is fetched from the server, correct?
[14:40] <j^2> jblaine: yep
[14:40] It does not, specifically, execute any recipes from the depended-upon cookbook unless told to.
[14:40] So 'depends foo' does not run recipe[foo] unless "include_recipe "foo"" is used
[14:40] jblaine: no, but as the 'required' recipes are being loaded things like attributes, library files, LWRPs etc will be read

Related, this sentence is brutal: :)

This field should be used whenever a feature that is included in another
cookbook should be run when this cookbook is run, such as including recipes,
using the same resources or providers in lightweight resource providers, custom
libraries, or definitions.

See here. There are several examples on the https://github.com/opscode/chef-docs/blob/master/chef_master/source/resource_cron.rst page where values that should be quoted like * and 1-5 are not, and so result in a syntax error and 4 respectively. :)

Every time I look up what values are valid for platform_family, I can't find them in the docs. We should copy them from this blog post and put them in the docs.

http://www.opscode.com/blog/2012/03/22/ohai-0-6-12-released/

There are a few typos on the "Community Plugins: Ohai" page.

http://docs.opscode.com/community_plugin_ohai.html

See comments in screenshot below.

Hey @jamescott,

One point of confusion among a lot of customers is the distinction between "data bag" and "data bag item". We sometimes reinforce this confusion by using the terms interchangeably, when they are not: data bags contain zero or more data bag items.

An example of this confusion is in the section about data bag item encryption: http://docs.opscode.com/chef/essentials_data_bags.html#encrypt-a-data-bag One never actually encrypts a bag as a whole; bag items are individually encrypted, or not. A bag can contain a mix of encrypted and unencrypted items, and in fact, encrypted items within the same bag need not share the same encryption key.

Because we say "data bag" instead of "item", the foregoing facts are not often known by customers and it leads to incorrect perceptions of the utility of encrypted data bags.

Could we do a sweep of the data bag topics and make sure we're precise about whether we're referring to bags or items?