Reverse Engineering Certbot Expand Option to Use with Another Client

My question is quite simple for this topic.

Your certbot has a --expand option to add some domain/sub-domain to an existing certificate.

But how this is working with the raw API?

We have a custom DNS validation system using your API and we currently have to create another certificate for the same domain if we just want to add a subdomain. This produce renewal challenge conflicts.

We would like to add the possibility to expand, add a subdomain on an existing certificate.

How could we do this with the API? Maybe I’m blind, but I can’t find anything on your official documentation.


1 Like

hi @Soullivaneuh

review the ACME spec:

you can also review the full code of certbot at github:✓&q=expand&type=


Well @ahaw021, thank you for the reply and the link but the homepage is a quite global precision. :slight_smile:

Maybe could you please show me which part could be interesting for my need?



I am going to be quite blunt. I don’t believe in spoon feeding people. Others may assist you with more precise responses if they choose so, but I do not roll that way.

I would spend time reading the source code on github it’s actually really well commented and the answer you seek is in the first few results :wink:

If you think that it’s unfair review how I approached a similar problem in the blog: Running Certbot on Windows - Phase 1

My problem was different from yours - i had os.geteuid() issues on windows but the concept is the same. Have a look figure it out and test it :smiley:


This is not a question of spoon feeding or not. I search on a web with no answer, I decide to post here if anybody have the correct knowledge to give a precise answer and earn us some time and help another people searching on the web and find this post.

Of course I’ll dig and test to find the solution thanks for your thread, I know we can do that such of thing, I myself an open-source contributor.

This is not the goal of this topic. If you have a precision to add to the subject, you can answer on this. If you don’t or don’t want to, that’s fine, just pass away to another topic.

But thank you I know what searching is, I was hoping this king of board was on an higher level than lmgtfy answers.

If this board has a private messages system, I’ll be glad to discuss about it with you. So now let’s close the debate about this out of topic subject to avoid to pollute the thread about this and let other people answer, if they want to.


I can’t give you entirely precise ACME guidance, but…

On the ACME API level, “expand” isn’t a thing. There’s just “issue a new certificate”.

Certbot’s --expand option purely relates to its interface and how it organizes certificates. It has no effect on the low-level issuance process.

If you explain the “renewal challenge conflicts”, someone may be able to help figure out what’s going wrong. :slight_smile:


that is correct

behind the scenes certbot creates a new certificate and update references in the old certificate to the new certificate. This saves having multiple version of the parent domain.

e.g if initial cert was for with one SAN for

If at a later date you wanted to add certbot would just create a new certificate that covers SAN and and update the live folder with the new key and certs

--expand tells Certbot to update an existing certificate with a new certificate that contains all of the old domains and one or more additional new domains.


proof of this behavior

if we look in the archives folder we can see this has happend

I had a few python issues on windows which is why there is 4 and 5

comparing the cert 1 (created beginning of the month) and cert 5 or 4 (created with expand today) you an see they are completely new certs with different serial numbers

You can also verify this on


Thanks for the answers which confirm my though about the --expand work of certbot.

@mnordhoff the actual issue of our platform is if you want to add a subdomain to an existing certificate, you currently can’t.

You have to create a new certificate with the same domain (multiple domain certificate is not allowed) and you will have issue with renewal certificate challenge (different DNS record to update for the same domain).

I think I’ll rework the logic to restrict to one certificate per domain and allow subdomain adding which will strictly recreate a cert, as the certbot does.

Thanks for the clarifications.

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.